API introduction

The Kayle ID API is a REST API with JSON request and response bodies. The hosted base URL is https://api.kayle.id. If you’re self-hosting, substitute your own host. All endpoints documented in this reference live under /v1/.

Authentication

Authenticate every request with an API key in the Authorization header:

Authorization: Bearer kk_...

API keys are minted in the dashboard under API keys. Each key is scoped to one organization and one or more scopes (sessions:read, sessions:write, webhooks:read, webhooks:write, analytics:read). Keys are hashed at rest with HMAC-SHA256 and shown in plaintext only at creation — losing a key means rotating it. The dashboard itself authenticates with session cookies. Those routes aren’t part of the public API surface and aren’t documented here.

Response envelope

Every response uses the same shape:

{
  "data": { /* operation-specific object, or null on error */ },
  "error": null
}

Errors replace data with null and populate error:

{
  "data": null,
  "error": {
    "code": "UNKNOWN_CLAIM_KEY",
    "message": "Unknown claim key.",
    "hint": "Use a supported claim key from the share contract allowlist.",
    "docs": "https://kayle.id/docs/api/sessions#create"
  }
}

See the error reference for the full list of codes and HTTP status mappings.

Pagination

List endpoints return a pagination field alongside data:

{
  "data": [ /* up to `limit` items */ ],
  "pagination": {
    "limit": 25,
    "has_more": true,
    "next_cursor": "vs_..."
  },
  "error": null
}

To fetch the next page, pass starting_after=<next_cursor> on the next request. limit is bounded between 1 and 100 (default 10). When has_more is false, next_cursor is null and you’ve reached the end of the list.

curl "https://api.kayle.id/v1/sessions?limit=50&starting_after=vs_..."  \
  -H "Authorization: Bearer kk_..."

Identifiers

Resources use prefixed IDs so they’re self-describing in logs:

Prefix	Resource
`vs_`	Verification session
`va_`	Verification attempt
`whe_`	Webhook endpoint
`whk_`	Webhook encryption key
`whd_`	Webhook delivery
`wha_`	Webhook delivery attempt
`evt_`	Event
`kk_`	API key (only the secret; the key record uses a UUID)

Versioning

The API is versioned in the URL path (/v1/). Breaking changes ship under a new version path. Backwards-compatible additions — new optional fields, new event types, new endpoints — happen in place under /v1/. The OpenAPI document for the version you’re calling is available at GET /openapi, and an interactive Scalar UI lives at GET /reference. The OpenAPI snapshot in this docs site is regenerated from a running API. From the repo root with the local API running:

bun ./apps/api/scripts/dump-openapi.ts > docs/api-reference/openapi.json

The script normalises a couple of @hono/zod-openapi output quirks (bumps the spec to OpenAPI 3.1, rewrites Hono path parameters into {param} form, gives the response envelope’s nullable error field an explicit type) so Mintlify can validate it.

What’s not documented here

The /v1/verify/* endpoints used by the verify web app and mobile clients (WebSocket plus a few public REST helpers) are part of the user-facing flow, not the partner integration surface. You don’t call them directly — see How it works for the role they play and Mobile handoff for the protocol details.

SDKs

REST only for now. Server-side SDKs are planned; until then, generate a client from the OpenAPI document if you want a typed wrapper.

Introduction

Endpoints

Webhook events

Authentication

Response envelope

Identifiers

Versioning

What’s not documented here

SDKs

​Authentication

​Response envelope

​Pagination

​Identifiers

​Versioning

​What’s not documented here

​SDKs

Authentication

Response envelope

Pagination

Identifiers

Versioning

What’s not documented here

SDKs