Sign in
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
  }
}

Changes

Changed in 6 of the 90 revisions of this API.7

  • 43ad1ce9a1522See the full diff
    • ○

      the endpoint scheme security dashboard was removed from the API

      api-security-removed

    • ○

      the endpoint scheme security rootKey was removed from the API

      api-security-removed

    This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • db25ebfde9a61See the full diff
    • ○

      the response property pagination became required for the status 200

      response-property-became-required

  • 1f6cb66aa3df1See the full diff
    • ○

      the endpoint scheme security dashboard was added to the API

      api-security-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • de540bf344531See the full diff
    • ○

      added the optional property data/items/lastUsedAt to the response with the 200 status

      response-optional-property-added

  • 551df53dd45d1See the full diff
    • ○

      added the non-success response with the status 429

      response-non-success-status-added

  • 9a9c22b6dd091See the full diff
    • ○

      api operation id listKeys removed and replaced with apis.listKeys

      api-operation-id-removed