API keys

API version

2026-11-11 (latest)next (preview)

CurrentDownload OpenAPI (JSON)Versioning

Create an API key

POST /api/v1/keys/create Session only

Mint a bl_live_ key. Interactive sessions only: an API key gets 403, because keys cannot mint keys. The session token must be under 5 minutes old, or the body must include the account password; otherwise the response is 428 (a step-up prompt, not a sign-out). At most 10 active keys per user and 5 creations per hour. Lifetime is capped at 365 days by default (an omitted or longer expiresInDays is clamped). llm:* scopes can always be granted; any other scope must be one you hold in your organization. The plaintext key is returned once, with Cache-Control: no-store.

Authentication

• Console session token only (API keys are refused)

Request body

application/json Required

• name string Required

  Maximum length

  100

• type string

  A label for the key's purpose. Capability comes from scopes.

  One of

  AGENT NORMAL LLM

  Default

  NORMAL

• scopes array of strings or null

  Scopes to grant. Empty uses the type's default (NORMAL keys get llm:access, llm:chat).

  Examples

  ["llm:access","llm:chat"]

• expiresInDays integer or null

  Minimum

  1

• password string (password) or null

  Account password, required when the session token is older than 5 minutes.

Responses

• 200 The new key. Store it now; it is never shown again.

  application/json

  Body (application/json)

  • id string
  • key string

    The plaintext key, starting bl_live_.

  • key_prefix string
  • name string
  • type string
  • scopes array of strings
  • expires_at string (date-time) or null
  • created_at string (date-time)
  • warning string
• 401 Missing, invalid, expired or revoked credentials.Error envelope
• 403 The credential is valid but lacks a required scope or permission.Error envelope
• 428 Step-up required. Re-send with password, or sign in again.Error envelope
• 429 A per-key request limit was exceeded, or the rate limiter could not be reached (it fails closed). There is no Retry-After for a window limit; wait for the next window. A concurrency limit, when configured, also returns 429, with Retry-After.Error envelope

Example

cURLCopy

curl -X POST "https://api.breachline.io/api/v1/keys/create" \
  -H "Authorization: Bearer $BREACHLINE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

Example 200 responseCopy

{
  "id": "string",
  "key": "string",
  "key_prefix": "string",
  "name": "string",
  "type": "string",
  "scopes": [
    "string"
  ],
  "expires_at": "2026-11-11T00:00:00Z",
  "created_at": "2026-11-11T00:00:00Z",
  "warning": "string"
}

List API keys

GET /api/v1/keys/list

The caller's active keys. Plaintext is never returned; key_prefix identifies each key. An API key needs keys:read.

Authentication

• API key in X-API-Key
• API key or session token in Authorization: Bearer

Responses

• 200 Keys.

  application/json

  Body (application/json)

  • keys array of objects
    10 fields in keys

    • id string
    • name string
    • type string
    • scopes array of strings
    • key_prefix string
    • expires_at string or null
    • is_active boolean
    • is_expired boolean
    • last_used_at string or null
    • created_at string
• 401 Missing, invalid, expired or revoked credentials.Error envelope
• 403 The credential is valid but lacks a required scope or permission.Error envelope
• 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

  application/json

  Headers

  • X-Request-ID string

    The request's correlation id (yours, or one BreachLine generated). Quote it to support.

  • Retry-After integer

    Seconds to wait before retrying.

  Body (application/json)

  • detail string Required
  • retry_after integer Required

    Always

    60

Example

cURLCopy

curl "https://api.breachline.io/api/v1/keys/list" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"

Example 200 responseCopy

{
  "keys": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "scopes": [
        "string"
      ],
      "key_prefix": "string",
      "expires_at": "string",
      "is_active": true,
      "is_expired": true,
      "last_used_at": "string",
      "created_at": "string"
    }
  ]
}

Revoke an API key

DELETE /api/v1/keys/{key_id}

Revocation is immediate. An API key needs keys:revoke.

Authentication

• API key in X-API-Key
• API key or session token in Authorization: Bearer

Path parameters

• key_id string Required

Responses

• 200 Revoked.

  application/json

  Body (application/json)

  • success boolean
  • message string
• 401 Missing, invalid, expired or revoked credentials.Error envelope
• 403 The credential is valid but lacks a required scope or permission.Error envelope
• 404 The resource does not exist or is not visible to this caller.Error envelope
• 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

  application/json

  Headers

  • X-Request-ID string

    The request's correlation id (yours, or one BreachLine generated). Quote it to support.

  • Retry-After integer

    Seconds to wait before retrying.

  Body (application/json)

  • detail string Required
  • retry_after integer Required

    Always

    60

Example

cURLCopy

curl -X DELETE "https://api.breachline.io/api/v1/keys/{key_id}" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"

Example 200 responseCopy

{
  "success": true,
  "message": "string"
}

Rotate an API key

POST /api/v1/keys/refresh/{key_id} Session only

Issue a new secret for an existing key; the old secret stops working at once. Interactive sessions only (an API key gets 403), and the account password is required (401 if wrong).

Authentication

• Console session token only (API keys are refused)

Path parameters

• key_id string Required

Request body

application/json Required

• password string (password) Required

Responses

• 200 The new plaintext key, shown once.

  application/json

  Body (application/json)

  • key string
  • warning string
• 401 Missing, invalid, expired or revoked credentials.Error envelope
• 403 The credential is valid but lacks a required scope or permission.Error envelope
• 404 The resource does not exist or is not visible to this caller.Error envelope
• 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

  application/json

  Headers

  • X-Request-ID string

    The request's correlation id (yours, or one BreachLine generated). Quote it to support.

  • Retry-After integer

    Seconds to wait before retrying.

  Body (application/json)

  • detail string Required
  • retry_after integer Required

    Always

    60

Example

cURLCopy

curl -X POST "https://api.breachline.io/api/v1/keys/refresh/{key_id}" \
  -H "Authorization: Bearer $BREACHLINE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "string"
  }'

Example 200 responseCopy

{
  "key": "string",
  "warning": "string"
}