Getting Started
Authentication methods, rate limits, and error handling reference.
Accessing the API
All API requests must be authenticated. Choose between JWT Bearer tokens for user-context operations or API Keys for machine-to-machine integrations.
Base URL: http://localhost:3000/api/v1
When to use
JWT tokens are used for user-context operations — dashboard access, compliance reviews, case management, and billing. They expire after 15 minutes and must be refreshed.
Step 1 — Authenticate
POST /api/v1/auth/login
{
"email": "admin@yourfirm.com",
"password": "yourpassword"
}Step 2 — Use the token
GET /api/v1/auth/me Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Step 3 — Refresh when expired
POST /api/v1/auth/refresh
{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}MFA Support
If MFA is enabled on the account, include the mfa_code field in the login request with the current TOTP code from your authenticator app.
Postman Collection
Download the full API collection, regenerated live from the OpenAPI spec. Import directly into Postman or Insomnia.
All endpoints
96 requests across 15 categories
Always up-to-date
Regenerated on every download from the live OpenAPI spec
Pre-configured auth
Environment variables for JWT and API Key pre-wired
Endpoint
/api/v1/health/postman-collectionPublic · No auth required · uses NEXT_PUBLIC_API_BASE_URLHow to import
- Click Download Collection above to save
kyconnect_postman_collection.json - In Postman: File → Import → drag and drop the file
- Set the
KYCONNECT_BASE_URLvariable tohttp://localhost:3000 - Set
KYCONNECT_JWTorKYCONNECT_API_KEYin your environment
Rate Limits
| Endpoint | Limit | Window |
|---|---|---|
| General API | 100 requests | per minute / IP |
| POST /auth/login | 10 attempts | per hour / IP |
| POST /onboarding/individual | 5 submissions | per 2 hours / email |
| POST /auth/forgot-password | 10 attempts | per hour / IP |
| Webhooks | Unlimited | — |
Rate-limited responses return HTTP 429 with a Retry-After header.
Error Response Format
{
"statusCode": 400,
"message": ["email must be a valid email"],
"error": "Bad Request"
}| Status Code | Meaning |
|---|---|
| 400 | Validation error – check the message array for field details |
| 401 | Authentication failed – missing or expired token/key |
| 403 | Authorization failed – insufficient role or scope |
| 404 | Resource not found |
| 409 | Conflict – duplicate resource or state mismatch |
| 422 | Unprocessable entity – business rule violation |
| 429 | Rate limit exceeded – back off and retry |
| 500 | Internal server error – contact support |
Authentication
Login, tokens, MFA, and session management
API Keys
Generate and manage machine-to-machine credentials
User Management
Invite team members and manage roles
Onboarding
Submit and manage KYC/KYB customer cases
Verification
Start KYC sessions and fetch results from identity providers
AML Screening
Real-time sanctions, PEP, and adverse media checks
Audit Trail
Immutable, hash-chained compliance audit logs
Billing
Subscriptions, invoices, and usage metering
Wallet
Balance, ledger, and payment methods for credit top-ups
Firms
Register your organisation and manage firm-level settings
DocuSign
eSignature integration for KYC agreements and T&C collection
Metric Pricing
Per-feature pricing for verifications, AML checks, and database services
Storage
Secure asset retrieval via pre-signed URLs
Demo Bookings
Request a personalised platform demo
Health
Liveness and readiness probes