Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
apis

List API keys

Retrieve a paginated list of API keys for dashboard and administrative interfaces.

Use this to build key management dashboards, filter keys by user with externalId, or retrieve key details for administrative purposes. Each key includes status, metadata, permissions, and usage limits.

Important: Set decrypt: true only in secure contexts to retrieve plaintext key values from recoverable keys.

Required Permissions

Your root key must have one of the following permissions for basic key listing:

  • api.*.read_key (to read keys from any API)
  • api.<api_id>.read_key (to read keys from a specific API)

Additionally, you need read access to the API itself:

  • api.*.read_api or api.<api_id>.read_api

Additional permission required for decrypt functionality:

  • api.*.decrypt_key or api.<api_id>.decrypt_key
post/v2/apis.listKeys

Request body

apiIdstring required

The API namespace whose keys you want to list. Returns all keys in this API, subject to pagination and filters.

limitinteger

Maximum number of keys to return per request. Balance between response size and number of pagination calls needed.

cursorstring

Pagination cursor from previous response to fetch next page. Use when hasMore: true in previous response.

externalIdstring

Filter keys by external ID to find keys for a specific user or entity. Must exactly match the externalId set during key creation.

decryptboolean

When true, attempts to include the plaintext key value in the response. SECURITY WARNING:

  • This requires special permissions on the calling root key
  • Only works for keys created with 'recoverable: true'
  • Exposes sensitive key material in the response
  • Should only be used in secure administrative contexts
  • Never enable this in user-facing applications
revalidateKeysCacheboolean

EXPERIMENTAL: Skip the cache and fetch the keys directly from the database. This ensures you see the most recent state, including keys created moments ago. Use this when:

  • You've just created a key and need to display it immediately
  • You need absolute certainty about the current key state
  • You're debugging cache consistency issues

This parameter comes with a performance cost and should be used sparingly.

Example request

{
  "apiId": "api_1234abcd",
  "cursor": "key_1234abcd",
  "externalId": "user_1234abcd"
}

Response

Successfully retrieved paginated keys. Use the pagination cursor for additional results when hasMore: true.

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "keyId": "key_1234567890abcdef",
      "start": "sk_test_abc123",
      "enabled": true,
      "name": "Production API Key",
      "createdAt": 1701425400000,
      "updatedAt": 1701425400000,
      "lastUsedAt": 1701425400000,
      "expires": 1735689600000,
      "permissions": [
        "documents.read",
        "documents.write"
      ],
      "roles": [
        "editor",
        "viewer"
      ],
      "credits": {
        "remaining": 1000,
        "refill": {
          "interval": "daily",
          "amount": 1000,
          "refillDay": 15
        }
      },
      "identity": {
        "ratelimits": [
          {
            "id": "rl_1234567890abcdef",
            "name": "api_requests",
            "limit": 1000,
            "duration": 3600000,
            "autoApply": true
          }
        ]
      },
      "plaintext": "sk_test_abc123def456",
      "ratelimits": [
        {
          "id": "rl_1234567890abcdef",
          "name": "api_requests",
          "limit": 1000,
          "duration": 3600000,
          "autoApply": true
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ==",
    "hasMore": true
  }
}