Authentication API

The Authentication API handles user verification and KYC (Know Your Customer) processes in your TraderPal Connect integration.

KYC Verification

Start Verification

POST /v1/auth/verify

Start the KYC verification process for a user.

Request Body

{
  "userId": "usr_123456789",
  "verificationType": "identity",
  "documentType": "passport",
  "country": "US"
}

Response

{
  "verificationId": "ver_123456789",
  "status": "pending",
  "createdAt": "2024-01-01T00:00:00Z",
  "expiresAt": "2024-01-01T01:00:00Z"
}

Upload Documents

POST /v1/auth/verify/{verificationId}/documents

Upload verification documents.

Request Body

{
  "documentType": "passport",
  "files": [
    {
      "type": "front",
      "content": "base64_encoded_image"
    }
  ]
}

Response

{
  "verificationId": "ver_123456789",
  "status": "under_review",
  "updatedAt": "2024-01-01T00:10:00Z"
}

Check Verification Status

GET /v1/auth/verify/{verificationId}

Check the status of a verification process.

Response

{
  "verificationId": "ver_123456789",
  "status": "approved",
  "documentType": "passport",
  "updatedAt": "2024-01-01T00:30:00Z",
  "expiresAt": "2025-01-01T00:30:00Z"
}

Two-Factor Authentication

Enable 2FA

POST /v1/auth/2fa/enable

Enable two-factor authentication for a user.

Request Body

{
  "userId": "usr_123456789",
  "type": "authenticator"
}

Response

{
  "secret": "ABCDEFGHIJKLMNOP",
  "qrCode": "data:image/png;base64,..."
}

Verify 2FA

POST /v1/auth/2fa/verify

Verify a 2FA code.

Request Body

{
  "userId": "usr_123456789",
  "code": "123456"
}

Response

{
  "verified": true,
  "timestamp": "2024-01-01T00:00:00Z"
}

Verification Statuses

Status	Description
pending	Verification initiated
under_review	Documents uploaded and being reviewed
approved	Verification approved
rejected	Verification rejected
expired	Verification request expired

Error Codes

Code	Description
400	Invalid request parameters
401	Invalid verification credentials
404	Verification not found
422	Invalid document format

Examples

Start Identity Verification

const verification = await client.auth.startVerification({
  userId: 'usr_123456789',
  verificationType: 'identity',
  documentType: 'passport',
  country: 'US'
});

console.log(verification.verificationId);

Enable 2FA

const twoFactor = await client.auth.enable2FA({
  userId: 'usr_123456789',
  type: 'authenticator'
});

console.log(twoFactor.qrCode);

Best Practices

1. Document Handling

   • Validate document formats before upload
   • Implement secure file handling
   • Monitor upload status

2. 2FA Implementation

   • Provide backup codes
   • Implement rate limiting
   • Handle timezone differences

3. Security

   • Encrypt sensitive data
   • Implement session management
   • Monitor suspicious activities

Next Steps

• Users API - Learn about user management
• Security Guide - Understand security best practices
• Error Handling - Learn about error handling