Authentication

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

Endpoint	Method	Required Permission	Description
`/kyc`	`POST`	`kyc:create`	Initiate a new KYC check
`/kyc/{job_id}`	`GET`	`kyc:read`	View KYC check results
`/exports/{jobId}`	`GET`	`kyc:export`	Export KYC results (PDF)
`/kyc/adverse-media`	`POST`	`kyc:create`	Perform adverse media check
`/kyc/web-validation`	`POST`	`kyc:create`	Validate website URLs
`/kyc/crypto`	`POST`	`kyc:create`	Check cryptocurrency wallets
`/kyc/documents/{type}`	`POST`	`kyc:create`	Extract document data
`/kyc/jobs`	`POST`	`kyc:create`	Create batch job
`/kyc/jobs/{job_id}`	`GET`	`kyc:read`	Get batch job status
`/kyc/workflows`	`POST`	`kyc:create`	Create workflow
`/kyc/workflows`	`GET`	`kyc:read`	List workflows
`/kyc/workflows/{id}`	`GET`	`kyc:read`	Get workflow details
`/kyc/workflows/{id}`	`PUT`	`kyc:create`	Update workflow
`/kyc/workflows/{id}`	`DELETE`	`kyc:create`	Delete workflow
`/kyc/sessions`	`POST`	`kyc:create`	Create session
`/kyc/sessions`	`GET`	`kyc:read`	List sessions
`/kyc/sessions/{id}`	`GET`	`kyc:read`	Get session details
`/kyc/sessions/{id}`	`PATCH`	`kyc:create`	Update session status
`/kyc/sessions/{id}`	`DELETE`	`kyc:create`	Delete session

Watchlist Operations

Endpoint	Method	Required Permission	Description
`/kyc/watchlists`	`POST`	`watchlist:create`	Create a new watchlist
`/kyc/watchlists`	`GET`	`watchlist:list`	List all watchlists
`/kyc/watchlists/{id}`	`GET`	`watchlist:read`	Get watchlist details
`/kyc/watchlists/{id}`	`PATCH`	`watchlist:update`	Update watchlist config
`/kyc/watchlists/{id}`	`DELETE`	`watchlist:delete`	Delete a watchlist
`/kyc/watchlists/{id}/subjects`	`POST`	`watchlist:update`	Add subject to watchlist
`/kyc/watchlists/{id}/subjects/batch`	`POST`	`watchlist:update`	Batch add subjects
`/kyc/watchlists/{id}/subjects/{subject_id}`	`DELETE`	`watchlist:update`	Remove subject

Usage & Monitoring

Endpoint	Method	Required Permission	Description
`/kyc/usage`	`GET`	`usage:read`	View usage metrics
`/health`	`GET`	None	Basic health check (public)
`/health/ready`	`GET`	`health:readiness_check`	Readiness check with dependencies

Tenant Management

Endpoint	Method	Required Permission	Description
`/kyc/tenants`	`POST`	`tenant:manage`	Create tenant (admin)
`/kyc/tenants/me`	`GET`	`tenant:read`	Get own tenant configuration
`/kyc/tenants/{id}`	`GET`	`tenant:manage`	Get tenant details (admin)
`/kyc/tenants/{id}`	`PUT`	`tenant:manage`	Update tenant (admin)
`/kyc/tenants/{id}`	`DELETE`	`tenant:manage`	Delete tenant (admin)
`/kyc/tenants/me/notification-channels`	`PATCH`	`tenant:read`	Update own notification channels
`/kyc/tenants/{id}/notification-channels`	`PATCH`	`tenant:manage`	Update notification channels (admin)
`/kyc/tenants/me/keywords`	`GET`	`keywords:read`	Get own keywords
`/kyc/tenants/me/keywords`	`PATCH`	`keywords:update`	Update own keywords
`/kyc/tenants/{id}/keywords`	`GET`	`keywords:read`	Get keywords (admin)
`/kyc/tenants/{id}/keywords`	`PATCH`	`keywords:update`	Update keywords (admin)
`/kyc/tenants/me/industries`	`GET`	`industries:read`	Get own industries
`/kyc/tenants/me/industries`	`PATCH`	`industries:update`	Update own industries
`/kyc/tenants/{id}/industries`	`GET`	`industries:read`	Get industries (admin)
`/kyc/tenants/{id}/industries`	`PATCH`	`industries:update`	Update industries (admin)
`/kyc/tenants/{id}/billing`	`PATCH`	`tenant:manage`	Update 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:

Contact your account administrator
Provide the intended use case and required permissions
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

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Webhooks

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

Header Format

Token Types

JWT Tokens (User Authentication)

API Keys (Machine-to-Machine)

Example Requests

Using JWT Token

Using API Key

Token Validation

Permissions

KYC Operations

Watchlist Operations

Usage & Monitoring

Tenant Management

Error Responses

401 Unauthorized

403 Forbidden

Getting API Keys

​Header Format

​Token Types

​JWT Tokens (User Authentication)

​API Keys (Machine-to-Machine)

​Example Requests

​Using JWT Token

​Using API Key

​Token Validation

​Permissions

​KYC Operations

​Watchlist Operations

​Usage & Monitoring

​Tenant Management

​Error Responses

​401 Unauthorized

​403 Forbidden

​Getting API Keys

Header Format

Token Types

JWT Tokens (User Authentication)

API Keys (Machine-to-Machine)

Example Requests

Using JWT Token

Using API Key

Token Validation

Permissions

KYC Operations

Watchlist Operations

Usage & Monitoring

Tenant Management

Error Responses

401 Unauthorized

403 Forbidden

Getting API Keys