Authentication & SDK Token Generation

AttestID supports two authentication modes, used at different points in your integration:

Mode	Who uses it	Header(s)	Lifetime
API key	Backend applications	`API-Key` + `Access-Key-Id`	until revoked
SDK token	Web and mobile SDK clients	`Authorization: Bearer <sdk_token>`	10 minutes

API keys are used only for server-to-server communication. Client applications should use SDK tokens when interacting with KYC endpoints.

1. API key authentication

Used for account-management endpoints (/v1/account/*) and to generate SDK tokens (POST /v1/kyc/session).

Example headers:

API-Key: sk_live_7d0a...b31f
Access-Key-Id: ak_live_9f2c...

Both headers are required for Authentication. The access_key_id must belong to the same credential pair as the api_key.

Requests made with invalid, suspended, or inactive credentials will be rejected.

2. SDK token flow

SDK tokens allow browser and mobile applications to perform KYC operations without exposing backend API credentials.

The SDK token is generated by your backend and is associated with a specific user session.

Step 1: Generate an SDK token:

Your backend sends a request to AttestID using your API credentials:

POST /v1/kyc/session
API-Key: sk_live_...
Access-Key-Id: ak_live_...
Content-Type: application/json

{ "user_id": "user-123" }

Response:

{
  "sdk_token": "eyJhbGciOiJIUzI1NiIs...",
  "user_id": "user-123",
  "expires_in": 600
}

Step 2: Provide the token to the client application

Your backend returns the sdk_token to your frontend or mobile application (e.g. as the JSON response of your own /api/attestid-session proxy route see the SDK guide).

Step 3: Use the SDK token for KYC requests

The SDK includes the token in subsequent API requests:

Authorization: Bearer <sdk_token>

The token is required for KYC operations including:

POST /v1/kyc/start, GET /v1/kyc/liveness-credentials, POST /v1/kyc/complete,

These endpoints do not accept API key only a valid sdk_token.

SDK token expiration

SDK tokens:

Are valid for 10 minutes.
Are associated with the user_id provided during generation.
Cannot be used to authenticate another user's session.

If additional verification time is required, the SDK requests a new token through the configured token provider.

SDK token generation with the client SDK

Applications using @attestid/sdk do not need to manually manage token requests during normal usage.

The SDK supports two configuration approaches.

Server-side configuration

The client SDK receives backend-provided configuration and requests SDK tokens using the server-side credentials.

Example:

apiKey
accessKeyId

The API key remains protected on the server.

Client token provider configuration

The SDK calls a callback function provided by your application:

getSdkToken()

The callback should request a token from your backend. Your backend then communicates with AttestID using the API credentials.

The SDK automatically manages token reuse and refresh during the verification flow.

Summary diagram

┌─────────────┐        API-Key + Access-Key-Id        ┌──────────────┐
│ Your backend│ ─────────────────────────────────────────▶│ POST /kyc/   │
│ (holds      │                                           │   session    │
│  api_key)   │◀──────────────── sdk_token (10 min) ──────└──────────────┘
└─────┬───────┘
      │  hands sdk_token to client (your own API route)
      ▼
┌─────────────┐   Authorization: Bearer <sdk_token>        ┌──────────────┐
│ Browser /   │ ─────────────────────────────────────────▶ │ /kyc/start   │
│ Mobile app  │                                            │/kyc/liveness-│
│ (@attestid/ │◀──────────── verification result ───────── │  credentials │
│  sdk)       │                                            │ /kyc/complete│
└─────────────┘                                            └──────────────┘

1. API key authentication​

2. SDK token flow​

SDK token expiration​

SDK token generation with the client SDK​

Server-side configuration​

Summary diagram​