Skip to main content
All API requests require authentication using Bearer tokens. The token is sent in the Authorization header of every request.

​
Header Format

All authenticated requests must include the following header: 
Authorization: Bearer <token>
The token can be either:
  • JWT Token: An ID token from your authentication provider (Cognito)
  • API Key: A service-to-service API key generated via the auth service

​
Token Types

​
JWT Tokens (User Authentication)

JWT tokens are issued when users log in through your authentication provider. These tokens are temporary and expire after a set period (typically 1 hour). When to use: Web applications, mobile apps, user-facing integrations

​
API Keys (Machine-to-Machine)

API keys are permanent credentials for server-to-server integrations. They are generated via the auth service and associated with a specific role. When to use: Backend services, automated integrations, scheduled jobs

​
Example Requests

​
Using JWT Token

curl -X POST https://stg.kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {"full_name": "John Doe"},
    "list_name": "ofac"
  }'

​
Using API Key

curl -X POST https://stg.kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer sk_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {"full_name": "John Doe"},
    "list_name": "ofac"
  }'

​
Token Validation

The authorization service automatically:
  • Validates the token format and signature
  • Extracts tenant identification from the token
  • Verifies required permissions for the requested operation
  • Passes tenant context to the backend Lambda functions
You do not need to include tenant_id in request bodies - it is automatically extracted from your token.

​
Permissions

Each token is associated with specific permissions following the resource:action pattern. The required permission varies by endpoint:

​
KYC Operations

EndpointMethodRequired PermissionDescription
/kycPOSTkyc:createInitiate a new KYC check
/kyc/{job_id}GETkyc:readView KYC check results
/exports/{jobId}GETkyc:exportExport KYC results (PDF)
/kyc/adverse-mediaPOSTkyc:createPerform adverse media check
/kyc/web-validationPOSTkyc:createValidate website URLs
/kyc/cryptoPOSTkyc:createCheck cryptocurrency wallets
/kyc/documents/{type}POSTkyc:createExtract document data
/kyc/jobsPOSTkyc:createCreate batch job
/kyc/jobs/{job_id}GETkyc:readGet batch job status
/kyc/workflowsPOSTkyc:createCreate workflow
/kyc/workflowsGETkyc:readList workflows
/kyc/workflows/{id}GETkyc:readGet workflow details
/kyc/workflows/{id}PUTkyc:createUpdate workflow
/kyc/workflows/{id}DELETEkyc:createDelete workflow
/kyc/sessionsPOSTkyc:createCreate session
/kyc/sessionsGETkyc:readList sessions
/kyc/sessions/{id}GETkyc:readGet session details
/kyc/sessions/{id}PATCHkyc:createUpdate session status
/kyc/sessions/{id}DELETEkyc:createDelete session

​
Watchlist Operations

EndpointMethodRequired PermissionDescription
/kyc/watchlistsPOSTwatchlist:createCreate a new watchlist
/kyc/watchlistsGETwatchlist:listList all watchlists
/kyc/watchlists/{id}GETwatchlist:readGet watchlist details
/kyc/watchlists/{id}PATCHwatchlist:updateUpdate watchlist config
/kyc/watchlists/{id}DELETEwatchlist:deleteDelete a watchlist
/kyc/watchlists/{id}/subjectsPOSTwatchlist:updateAdd subject to watchlist
/kyc/watchlists/{id}/subjects/batchPOSTwatchlist:updateBatch add subjects
/kyc/watchlists/{id}/subjects/{subject_id}DELETEwatchlist:updateRemove subject

​
Usage & Monitoring

EndpointMethodRequired PermissionDescription
/kyc/usageGETusage:readView usage metrics
/healthGETNoneBasic health check (public)
/health/readyGEThealth:readiness_checkReadiness check with dependencies

​
Tenant Management

EndpointMethodRequired PermissionDescription
/kyc/tenantsPOSTtenant:manageCreate tenant (admin)
/kyc/tenants/meGETtenant:readGet own tenant configuration
/kyc/tenants/{id}GETtenant:manageGet tenant details (admin)
/kyc/tenants/{id}PUTtenant:manageUpdate tenant (admin)
/kyc/tenants/{id}DELETEtenant:manageDelete tenant (admin)
/kyc/tenants/me/notification-channelsPATCHtenant:readUpdate own notification channels
/kyc/tenants/{id}/notification-channelsPATCHtenant:manageUpdate notification channels (admin)
/kyc/tenants/me/keywordsGETkeywords:readGet own keywords
/kyc/tenants/me/keywordsPATCHkeywords:updateUpdate own keywords
/kyc/tenants/{id}/keywordsGETkeywords:readGet keywords (admin)
/kyc/tenants/{id}/keywordsPATCHkeywords:updateUpdate keywords (admin)
/kyc/tenants/me/industriesGETindustries:readGet own industries
/kyc/tenants/me/industriesPATCHindustries:updateUpdate own industries
/kyc/tenants/{id}/industriesGETindustries:readGet industries (admin)
/kyc/tenants/{id}/industriesPATCHindustries:updateUpdate industries (admin)
/kyc/tenants/{id}/billingPATCHtenant:manageUpdate billing (admin)

​
Error Responses

​
401 Unauthorized

{
  "message": "Unauthorized"
}
This occurs when:
  • The Authorization header is missing
  • The token format is invalid
  • The token has expired (JWT tokens only)

​
403 Forbidden

{
  "message": "User is not authorized to perform this action"
}
This occurs when:
  • The token is valid but lacks required permissions
  • The token’s associated role doesn’t grant access to the resource

​
Getting API Keys

To generate an API key for machine-to-machine authentication:
  1. Contact your account administrator
  2. Provide the intended use case and required permissions
  3. The API key will be generated with appropriate role-based permissions
For security, API keys should be:
  • Stored securely (environment variables, secrets manager)
  • Never committed to version control
  • Rotated periodically
  • Revoked immediately if compromised