> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compliance.legaltalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```http theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "message": "Unauthorized"
}
```

This occurs when:

* The `Authorization` header is missing
* The token format is invalid
* The token has expired (JWT tokens only)

### 403 Forbidden

```json theme={null}
{
  "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