Authentication

The platform has three authentication mechanisms, each scoped to a specific surface.

API keys (server → /v1/*)

Your server calls the public REST API with a bearer API key.

Authorization: Bearer ak_test_...   # test mode
Authorization: Bearer ak_live_...   # live mode

• Test keys are free and never expire. Live keys require an active billing plan or a funded prepaid wallet.
• Keys are shown once at creation. Store them in your secret manager.
• Every request is rate-limited per key. Exceeding the limit returns rate_limited.

SDK tokens (browser → iframe)

When you create a session, the API returns an sdk_token — a short-lived JWT (≤ 30 minutes) scoped to a single session. The iframe uses this token to authenticate its own API calls; it is not a general-purpose API key.

SDK tokens are single-session and cannot be used to create or list other sessions.

Session cookies (dashboards)

The tenant portal and internal admin console use opaque session cookies:

• __Host-kyc_portal_session — 30-day sliding window, 24 h rolling refresh.
• __Host-kyc_admin_session — 12-hour absolute lifetime. Admins log in via magic link.

Both cookies are HttpOnly; Secure; SameSite=Lax; Path=/, with CSRF double- submit protection on mutating requests.

Never mix auth methods

Each route accepts exactly one auth type. Do not send a bearer API key to /internal/*, and do not use portal cookies to call /v1/* — both will return authentication_required.