API keys

API keys let one of your own services authenticate to Reconbanker without a human login. They are the credential the External API accepts — for example, an SMS-relay server that submits one-time codes for assisted login.

The endpoints on this page manage keys and are themselves JWT-protected: you call them as the logged-in user with Authorization: Bearer <jwt>. The keys they mint are then used on the /v1 endpoints with a different header.

Key format

A key looks like this:

rbk_abcd1234_secret1234567890abcdef1234567890abcdef1234567890abcdef

It has three parts: the rbk_ marker, an 8-character prefix that identifies the key, and a 64-character secret. Reconbanker stores only a hash of the secret, so the full key is shown to you once, at creation, and can never be retrieved again. The prefix is not secret — it is what you see in listings so you can recognize a key.

Scopes

Every key carries one or more scopes. A scope is the permission to call a specific part of the External API.

At least one scope is required. A key calling an endpoint outside its scopes gets 403 Forbidden.

Account scope

A key can be limited to specific accounts through account_ids:

• An array of account UUIDs — the key may only touch those accounts.
• null — the key may touch every account you own.

A key used against an account outside its list gets 403 Forbidden, even if the account belongs to you.

List API keys

Use this endpoint to list the keys you have created. Secrets are never included.

GET /me/api-keys

Response 200 OK:

{
  "keys": [
    {
      "id": "uuid",
      "name": "SMS relay",
      "prefix": "abcd1234",
      "scopes": ["otp:write", "status:read"],
      "account_ids": null,
      "created_at": "2026-01-01T00:00:00.000Z",
      "last_used_at": null,
      "revoked_at": null
    }
  ],
  "available_scopes": ["otp:write", "status:read"]
}

• prefix - the non-secret identifier; the full key is never returned here.
• account_ids - null means all your accounts; otherwise the allowed account UUIDs.
• last_used_at - when the key last authenticated a request, or null if never used.
• revoked_at - non-null once the key has been revoked.
• available_scopes - every scope the platform supports, so you know what you can request.

Create an API key

Use this endpoint to mint a new key. The plaintext key comes back only in this response — store it now, because you cannot read it again.

POST /me/api-keys
Content-Type: application/json

Request body:

{
  "name": "SMS relay",
  "scopes": ["otp:write", "status:read"],
  "account_ids": ["7e9a2b3c-4d5e-4f6a-9b8c-1d2e3f4a5b6c"]
}

• name - required. 1 to 100 characters. A label so you can recognize the key later.
• scopes - required. At least one of "otp:write", "status:read".
• account_ids - optional. An array of account UUIDs, or null (the default) for all your accounts.

Response 201 Created:

{
  "id": "uuid",
  "name": "SMS relay",
  "prefix": "abcd1234",
  "scopes": ["otp:write", "status:read"],
  "account_ids": ["7e9a2b3c-4d5e-4f6a-9b8c-1d2e3f4a5b6c"],
  "created_at": "2026-01-01T00:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null,
  "key": "rbk_abcd1234_secret1234567890abcdef1234567890abcdef1234567890abcdef"
}

The key field is the full secret. It appears here and nowhere else — if you lose it, revoke the key and create a new one.

• 400 Bad Request - the body is missing name, has an empty or invalid scopes array, or has an account_ids value that is not a list of UUIDs.

Revoke an API key

Use this endpoint to permanently disable a key. Any request that uses it afterwards gets 401 Unauthorized with code INVALID_API_KEY.

DELETE /me/api-keys/:id

Responses:

• 204 No Content - revoked.
• 404 Not Found - no key with that id belongs to you.

See also

• External API - where you use the keys you create here.
• Automate OTP submission - the end-to-end integration walkthrough.
• Assisted login and OTP - what these keys are typically used for.