API keys

Every VerifyAI request authenticates with a vai_… API key in the X-API-Key header. This page covers managing those keys: what a key looks like, how to create and revoke them, and the one rule that trips people up — the full key is shown exactly once.

For how keys are used on a request, see Authentication.

The key object

A key is scoped to a single customer account. The server stores only a SHA-256 hash of the key — never the plaintext — so a key that's lost can only be replaced, never recovered.

{
  "id": "key_4f9a2c",
  "name": "Production backend",
  "key_prefix": "vai_live_8x9k…",
  "scope": "full",
  "active": true,
  "customer_id": "cus_forest1",
  "rate_limit_per_minute": 100,
  "rate_limit_per_hour": 6000,
  "last_used_at": "2026-06-01T11:58:02Z",
  "created_at": "2026-05-12T14:30:00Z",
  "expires_at": null
}

Fields

Managing keys in the dashboard

The fastest path is the dashboard, which is the supported way to author keys today:

1. Open Dashboard → Settings → API keys.
2. Click Create key, give it a name, and pick a scope.
3. Copy the full vai_… value from the one-time reveal into your secret manager.
4. To retire a key, click Revoke next to it. Revocation takes effect immediately — in-flight requests using that key start returning 401.

Sandbox keys are issued automatically when you sign up; their usage is free and never bills your account.

REST contract

The endpoints below expose the same operations programmatically. They are account-scoped — a key can only manage keys belonging to its own customer — and they authenticate exactly like every other VerifyAI request.

Authentication

List keys

GET /api/v1/api-keys

Returns every key on your account, newest first. The plaintext secret is never included — only id, key_prefix, and metadata.

curl https://verify.switchlabs.dev/api/v1/api-keys \
-H "X-API-Key: vai_your_api_key"

{
  "data": [
    {
      "id": "key_4f9a2c",
      "name": "Production backend",
      "key_prefix": "vai_live_8x9k…",
      "scope": "full",
      "active": true,
      "rate_limit_per_minute": 100,
      "rate_limit_per_hour": 6000,
      "last_used_at": "2026-06-01T11:58:02Z",
      "created_at": "2026-05-12T14:30:00Z",
      "expires_at": null
    }
  ]
}

Create a key

POST /api/v1/api-keys

Creates a new key on your account. The response is the only place the full secret appears.

Body parameters

curl -X POST https://verify.switchlabs.dev/api/v1/api-keys \
-H "X-API-Key: vai_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "name": "iOS app", "scope": "verify_only" }'

{
  "id": "key_7b1d8e",
  "name": "iOS app",
  "key": "vai_live_3q5w8r1t6y2u4i9o0a3s8x9k2m4n7p3q",
  "key_prefix": "vai_live_3q5w…",
  "scope": "verify_only",
  "active": true,
  "rate_limit_per_minute": 100,
  "rate_limit_per_hour": 6000,
  "created_at": "2026-06-01T12:00:00Z",
  "expires_at": null
}

The key field is present only on this create response. Every other endpoint returns key_prefix instead.

Revoke a key

DELETE /api/v1/api-keys/:id

Revokes a key by its key_ id. Revocation is immediate and permanent — the key flips to active: false and all future requests with it return 401. There is no un-revoke; create a fresh key instead.

curl -X DELETE https://verify.switchlabs.dev/api/v1/api-keys/key_7b1d8e \
-H "X-API-Key: vai_your_api_key"

{ "id": "key_7b1d8e", "active": false, "revoked_at": "2026-06-01T12:05:00Z" }

Scopes

A key's scope limits what it can do. Use the narrowest scope that works:

Rate limits

Each key carries its own rate_limit_per_minute (default 100) and rate_limit_per_hour (default 6000). When a key exceeds either window, requests return 429 with a Retry-After header indicating how many seconds to wait. Limits are enforced per key, so splitting traffic across keys gives each its own budget. Contact support to raise the defaults on a key.

Errors

What's next

• Authentication — how to send a key on every request, plus rotation guidance.
• Customers API — the account a key acts on behalf of.
• Verify endpoint — what a vai_ key authorizes you to call.