Skip to content

Latest commit

 

History

History
224 lines (148 loc) · 5.59 KB

QUICKSTART.md

File metadata and controls

224 lines (148 loc) · 5.59 KB

Quick Start Guide

This guide will help you get the IPification Showcase application up and running quickly.

Table of Contents

Prerequisites Checklist

  • Node.js >= 22.x installed
  • npm installed
  • IPification account credentials

5-Minute Setup

Step 1: Install Dependencies

npm install

Step 2: Configure Application

cp config/default.json.sample config/default.json

For a full field reference, see Sample Config Reference.

Edit config/default.json and add client configuration

Step 3: Start the Server

npm start

Step 4: Access the Application

  1. Open browser and navigate to:

    http://localhost:3000

  2. Select Auth Server (if multiple servers configured):

    • A dropdown appears at the top of the page showing available auth servers (e.g., "stage", "live")
    • Select the server you want to use for authentication
    • Your selection is saved and persists across page reloads

  3. Click "IP" button in PNV tab to test authentication

Auth Server Selection

If you configured multiple auth servers in config/default.json, you can switch between them:

  1. Dropdown Location: Top of the login page, next to the logo
  2. Selection Persistence: Your choice is saved to browser localStorage
  3. Reload Behavior: The selected server remains active after page reload
  4. Per-Request: Each authentication request uses your selected server

Example Use Cases:

  • Testing: Switch between stage and live servers without config changes
  • Development: Test against different environments easily
  • Demo: Show different server behaviors to clients

Single Server: If only one server is configured, no dropdown appears - the app uses that server automatically.

Testing Different Flows

Phone Number Verification (PNV)

  1. Go to PNV tab
  2. Enter phone number (optional for some flows)
  3. Click desired button:
    • IP: Carrier-based verification
    • IP+: Enhanced verification with mobile ID
    • IM: Instant messaging verification
    • SIM: SIM card verification

Quick Access Login

  1. Go to Login tab
  2. Click desired login method:
    • IP: Carrier-based login
    • IP+: Enhanced login
    • IM: Instant messaging login
    • SIM: SIM card login

Identity Services

  1. Go to Identity tab
  2. For Anonymous Identity: Click button directly
  3. For KYC Data: Enter phone number, then click "KYC"

Common Issues

Port Already in Use

Error: Port 3000 is already in use

Solution:

PORT=3001 npm start

Then access: http://<your-ip>:3001

Configuration Error

Error: Configuration error: auth_servers must be defined as an array in config

Solution:

  • Ensure auth_servers array is defined in config/default.json
  • Must contain at least one server with id and url fields
  • See Sample Config Reference for proper format

Error: Client not found

Solution:

  • Verify config/default.json exists
  • Check that user_flow matches configuration
  • Ensure client credentials are correct
  • Reference Sample Config Reference for required fields

Cannot Access from Mobile Device

Issue: Mobile device cannot reach the application

Solutions:

  1. Ensure desktop and mobile are on same network
  2. Check firewall settings
  3. Use machine's local IP (not localhost or 127.0.0.1)
  4. Verify port is not blocked

Authentication Fails

Issue: Authentication redirects to error page

Solutions:

  1. Verify redirect_uri in IPification dashboard matches:

    http://localhost:3000/auth/callback/<user_flow>/<server_id>

    Example: http://localhost:3000/auth/callback/pvn_ip/stage

  2. Check client_id and client_secret are correct

  3. Verify scope permissions match client configuration

  4. Ensure phone number format is E.164 (e.g., +1234567890)

  5. Confirm the selected auth server is accessible and properly configured

Development Mode

For development with auto-reload:

npm run dev

This uses nodemon to automatically restart the server when files change.

Environment Variables

Create a .env file for custom configuration:

PORT=3000
NODE_ENV=development

Supported NODE_ENV values: development, stage, production.

Next Steps

  • Read README.md for detailed documentation
  • Check API.md for API endpoint details
  • Review ARCHITECTURE.md for system design
  • Explore different user flows in the application

Getting Help