API Reference (Quick Index)
Base URL: https://api.attestid.brimsage.co.ls (production). All routes below are prefixed /v1 unless shown otherwise.
Auth column:
- API key:
X-API-Key+X-Access-Key-Idheaders, plus your client certificate (mutual TLS). See Authentication. - SDK token:
Authorization: Bearer <sdk_token>. - Dashboard: a logged-in dashboard user (these are the dashboard's own endpoints; most integrations use the dashboard UI instead).
Account & company management (/v1/account)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /account/register | none | Register your company. Sends a verification email. No API key is issued yet. |
| POST | /account/verify-email | none | Confirm the email with the token from the link. Activates the account and returns your first test API key (shown once). |
| POST | /account/resend-verification | none | Send a new verification link. Always returns the same message. |
| GET | /account/me | API key | Get your company's details. |
| POST | /account/me/keys | API key | Issue another API key (test or live). Shown once. |
| GET | /account/me/keys | API key | List key prefixes and metadata (no secrets). |
| DELETE | /account/me/keys/{key_id} | API key | Revoke a key. Irreversible. |
| DELETE | /account/me/data?user_id=... | API key | Schedule erasure of a user's personal data and photos within 72 hours (Lesotho Data Protection Act). |
See Creating a Company & Getting Your Keys for full request and response bodies.
KYC verification (/v1/kyc)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /kyc/session | API key | Exchange your API key for a 10-minute sdk_token bound to one user_id. Call only from your backend. |
| POST | /kyc/device/challenge | SDK token | Single-use nonce for device-key registration or for signing one capture. |
| POST | /kyc/device/register | SDK token | Register the device's capture-signing public key. |
| POST | /kyc/start | SDK token | Upload the ID photo (multipart/form-data: user_id, id_type, id_photo, consent_given_at, processing_purpose, plus optional capture-signing fields). Returns verification_id and the face-check session. |
| POST | /kyc/{verification_id}/liveness-retry | SDK token | Retry a failed face check without re-uploading the ID. Same response shape as /kyc/start. |
| POST | /kyc/complete | SDK token | Complete the verification after the face check (verification_id form field). Returns verified, status, message, failure_reason, document, checks and a signed attestation. |
| GET | /kyc/{verification_id} | SDK token | Retrieve a verification result, including attestation. |
| GET | /kyc/{verification_id}/documents?purpose=... | SDK token | Links to the captured ID photo and selfie, valid for 5 minutes. Every call is audit-logged with its purpose. |
POST /kyc/* requests accept an Idempotency-Key header for safe retries. The SDKs send it for you, and run the face check itself through AttestID endpoints that aren't part of the public API.
The JavaScript/React SDK and Flutter SDK wrap all of these calls.
Webhooks (/v1/webhooks)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /webhooks/configure | API key | Set or update your webhook URL. Returns a new signing secret, shown once. Starts a 24-hour rotation overlap if a secret already existed. |
| POST | /webhooks/rotation/confirm | API key | Stop signing with the previous secret immediately. |
| GET | /webhooks/configure | API key | Get your webhook URL, whether a secret is set, and when the previous secret stops signing. |
| DELETE | /webhooks/configure | API key | Remove your webhook URL and secrets; stops delivery. |
| GET | /company/webhook/deliveries | Dashboard | List recent delivery attempts and their status. |
See Webhooks for event types, payloads, retries, and how to verify the AttestID-Signature and AttestID-JWS headers.
Dashboard: keys and certificates (/v1/company)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /company/keys/{key_id}/rotate | Dashboard | Issue a replacement key. The old key keeps working for 24 hours. |
| POST | /company/keys/{new_key_id}/confirm-rotation | Dashboard | Revoke the replaced key immediately. |
| GET | /company/client-certificates | Dashboard | List your client certificates, including revoked and expired ones. |
| POST | /company/client-certificates | Dashboard | Issue a client certificate from your CSR (certificate_request, optional label). |
| DELETE | /company/client-certificates/{cert_id} | Dashboard | Revoke a certificate. Takes effect on the next request. |
Public keys
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /.well-known/jwks.json (no /v1 prefix) | none | AttestID's public signing keys, for verifying result attestations and the AttestID-JWS webhook header. |
Key, token and certificate cheat sheet
| Value | Format | Where it's used |
|---|---|---|
access_key_id | ak_live_... / ak_test_... | X-Access-Key-Id header, paired with api_key |
api_key | sk_live_... / sk_test_... | X-API-Key header. Shown only once, at creation |
| Client certificate | X.509, issued from your CSR, valid 365 days | Presented on the TLS connection for every API-key request |
sdk_token | Signed token, 10-minute expiry | Authorization: Bearer on all /kyc/* SDK calls |
| Webhook secret | whsec_... | Verifying AttestID-Signature. Shown only once |
attestation | ES256 JWS | Proof of a verification decision. Verify on your backend |
| Dashboard session | Signed session token, 8-hour expiry | Dashboard login. Not used by the SDK |
Common errors
| Status | When |
|---|---|
401 | Bad or missing API key, missing or invalid client certificate, or an expired SDK token |
402 | Plan limit reached (plan_limit_exceeded) or spend limit reached |
403 | The identity is under fraud review or has been flagged (fraud_review_required, identity_flagged_fraudulent) |
409 | A request with this Idempotency-Key is still processing (see Retry-After), or a liveness retry was refused |
410 | A liveness session, retry window or verification link has expired |
413 / 415 | Upload too large, or not a JPEG/PNG photo (or MP4/WebM/QuickTime video) |
422 | Invalid input, for example a consent timestamp older than 24 hours, an unknown processing_purpose, or a reused Idempotency-Key with a different body |
429 | Rate limited |
Support
For API keys, onboarding, or technical support: support@brimsage.co.ls