Skip to main content

​
Introduction

The user management system provides comprehensive functionality for onboarding, authenticating, and managing user accounts in a multi-tenant environment. All user operations support both international and US-specific configurations through environment routing.
All endpoints require the x-client-key header. For US environment routing, include x-us-env: true header or region=us query parameter.

​
User Lifecycle

Understanding the complete user journey helps you implement the right flows at the right time:

​
Lifecycle Stages

Registration

Multi-step onboarding process with email/phone verification and KYC data collection

Consent Management

GDPR/CCPA-compliant consent tracking collected during registration with immutable audit trails

Authentication

Secure login with optional OTP for enhanced security

Verification

Identity verification process with status tracking (UNVERIFIED → PENDING → VERIFIED)

Profile Management

View and update user information, settings, and verification status
Consent Collection: Step 4 requires creating a formal consent record via the Consent Management API before address submission. Pass the onboardingId to establish comprehensive regulatory compliance (GDPR, CCPA, E-Sign Act) with complete audit trails. After registration finalizes (Step 5 or 6), link the consent to the userId (Step 7). This is essential before users can access features like card issuance or wallet delegation.

​
Registration Flow

The registration process follows a sequential 7-step flow that collects required KYC information:
1

Email Verification

Send verification code to user’s email address and verify before proceeding
2

Phone Verification

Send SMS verification code to user’s phone number and verify
3

Personal Details

Collect name, date of birth, nationality, and SSN (US users only)
4

Consent Collection

Create formal consent record using the Consent Management API by passing the onboardingId. This is required for regulatory compliance (GDPR, CCPA, E-Sign Act) and must be completed before address submission.
5

Physical Address

Collect residential address. This step finalizes registration for non-US users or US users with same mailing address, returning userId and accessToken.
6

Mailing Address (Optional)

For US users only with different mailing address. This step finalizes registration and returns userId and accessToken.
7

Link Consent to User

After registration finalizes (Step 5 or 6), link the consent set to the userId using PATCH /v2/consent/onboarding/{consentSetId}.
The registration flow returns an onboardingId after email verification that must be passed through each subsequent step to maintain session continuity.

​
Authentication Methods

The platform supports multiple authentication patterns for different use cases:

​
Standard Login

Direct username/password authentication for registered users: 
POST /v1/auth/login
{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}
API Reference: POST /v1/auth/login Returns: Access token valid for 6 hours

​
OTP-Enhanced Login

For users with OTP enabled, an additional verification step is required:
  1. Check isOtpRequired from login response
  2. Request OTP code via POST /v1/auth/login/otp
  3. Submit login credentials with otpCode field
OTP codes are time-sensitive. Complete the OTP flow within the code expiration window (typically 5-10 minutes).

​
OAuth 2.0 Integration

For third-party applications, OAuth 2.0 with PKCE provides delegated authorization:
  • Full OAuth flow documentation: OAuth 2.0 Guide
  • Supports authorization code flow with PKCE
  • Refresh token support for long-lived sessions
See the Authentication Guide for detailed implementation patterns.

​
Verification States

Users progress through verification states as they complete identity checks:
StateDescriptionActions Available
UNVERIFIEDInitial state after registrationLimited account access, verification required
PENDINGVerification submitted, awaiting reviewFull functionality may be restricted
VERIFIEDIdentity confirmedFull account access
REJECTEDVerification failedContact support, may resubmit
Check verification status using GET /v1/user or GET /v1/user/verification before performing operations that require verified users.

​
Profile Management

Once registered, users can manage their account information:

​
Available Operations

  • View Profile: Get complete user details including verification status
  • Update Settings: Modify account preferences and security settings
  • Check Verification: Monitor KYC verification progress
  • Session Management: Login, logout, and token refresh

​
User Information Structure

{
  "id": "100a99cf-f4d3-4fa1-9be9-2e9828b20ebb",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-01",
  "phoneNumber": "7400846282",
  "phoneCountryCode": "+44",
  "verificationState": "VERIFIED",
  "addressLine1": "23 Werrington Bridge Rd",
  "city": "Peterborough",
  "zip": "PE6 7PP",
  "countryOfResidence": "GB",
  "countryOfNationality": "GB"
}

​
Security Considerations

​
Password Requirements

While specific requirements may vary by environment configuration, follow these best practices:
  • Minimum 8 characters
  • Include uppercase and lowercase letters
  • Include numbers and special characters
  • Avoid common passwords or dictionary words

​
Token Management

Access tokens are returned in two scenarios:
  1. After successful login: Use for immediate API access
  2. After completing registration: Initial authentication for new users
Access tokens expire after 6 hours. Implement token refresh logic or require re-authentication for long-running sessions.

​
Multi-Factor Authentication

OTP (One-Time Password) provides an additional security layer:
  • Sent via SMS to registered phone number
  • Time-limited codes
  • Required for sensitive operations when enabled

​
Regional Configurations

The API supports region-specific flows and requirements:

​
International Environment

  • Standard KYC requirements
  • Physical address only (no mailing address)
  • Country-specific field validation

​
US Environment

Access via x-us-env: true header or region=us parameter:
  • SSN (Social Security Number) required
  • US state field mandatory
  • Optional separate mailing address
  • Enhanced compliance requirements
US-specific fields (SSN, usState, mailing address) are required only when countryOfResidence = "US". Validation will fail if these are missing for US users.

​
Error Handling

Common error scenarios and resolutions:
Error: Email address already exists in the systemResolution: User should login instead of registering, or use password recovery if forgotten
Error: Email or phone verification code is incorrect or expiredResolution: Request a new verification code and try again within the expiration window
Error: Required fields missing for user’s country of residenceResolution: Ensure SSN and usState are provided for US users, validate all required fields based on countryOfResidence
Error: Access token or onboarding session expiredResolution: For onboarding, restart the registration flow. For access tokens, re-authenticate the user

​
Quick Start Guide

Get started with user management in 3 steps:
1

Register New User

Follow the Registration Guide to onboard new users with complete KYC data collection
2

Authenticate User

Implement login flows using the Authentication Guide with optional OTP support
3

Manage Profile

Access and update user information using the Profile Management Guide

Registration Guide

Step-by-step registration implementation with code examples

Consent Management

GDPR/CCPA-compliant consent tracking and audit trails

Authentication Guide

Login flows, OTP, and session management

Profile Management

View and update user information

API Reference

Complete endpoint documentation

​
Next Steps