---
title: "List API keys"
method: POST
path: "/v2/apis.listKeys"
tags: ["apis"]
---

# List API keys

`POST /v2/apis.listKeys`

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`

## Request body

- V2ApisListKeysRequestBody
  - `apiId` string, required — The API namespace whose keys you want to list. Returns all keys in this API, subject to pagination and filters.
  - `limit` integer — Maximum number of keys to return per request. Balance between response size and number of pagination calls needed.
  - `cursor` string — Pagination cursor from previous response to fetch next page. Use when `hasMore: true` in previous response.
  - `externalId` string — Filter keys by external ID to find keys for a specific user or entity. Must exactly match the externalId set during key creation.
  - `decrypt` boolean — 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
  - `revalidateKeysCache` boolean — 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.

## Response `200`

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

- V2ApisListKeysResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` KeyResponseData[], required — Array of API keys with complete configuration and metadata.
    - `keyId` string, required — Unique identifier for this key.
    - `start` string, required — First few characters of the key for identification.
    - `enabled` boolean, required — Whether the key is enabled or disabled.
    - `name` string — Human-readable name for this key.
    - `meta` object — Custom metadata associated with this key.
    - `createdAt` integer, required — Unix timestamp in milliseconds when key was created.
    - `updatedAt` integer — Unix timestamp in milliseconds when key was last updated.
    - `lastUsedAt` integer — Unix timestamp in milliseconds when key was last used for verification. This is an approximated value, accurate to within 5 minutes.
    - `expires` integer — Unix timestamp in milliseconds when key expires (if set).
    - `permissions` string[]
    - `roles` string[]
    - `credits` KeyCreditsData — Credit configuration and remaining balance for this key.
      - `remaining` integer, nullable, required — Number of credits remaining (null for unlimited).
      - `refill` KeyCreditsRefill — Configuration for automatic credit refill behavior.
        - `interval` 'daily' | 'monthly', required — How often credits are automatically refilled.
        - `amount` integer, required — Number of credits to add during each refill cycle.
        - `refillDay` integer — Day of the month for monthly refills (1-31). Only required when interval is 'monthly'. For days beyond the month's length, refill occurs on the last day of the month.
    - `identity` Identity
      - `id` string, required — Identity ID
      - `externalId` string, required — External identity ID
      - `meta` object — Identity metadata
      - `ratelimits` RatelimitResponse[] — Identity ratelimits
        - `id` string, required — Unique identifier for this rate limit configuration.
        - `name` string, required — Human-readable name for this rate limit.
        - `limit` integer, required — Maximum requests allowed within the time window.
        - `duration` integer, required — Rate limit window duration in milliseconds.
        - `autoApply` boolean, required — Whether this rate limit was automatically applied when verifying the key.
    - `plaintext` string — Decrypted key value (only when decrypt=true).
    - `ratelimits` RatelimitResponse[]
      - `id` string, required — Unique identifier for this rate limit configuration.
      - `name` string, required — Human-readable name for this rate limit.
      - `limit` integer, required — Maximum requests allowed within the time window.
      - `duration` integer, required — Rate limit window duration in milliseconds.
      - `autoApply` boolean, required — Whether this rate limit was automatically applied when verifying the key.
  - `pagination` Pagination, required — Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
    - `cursor` string — Opaque pagination token for retrieving the next page of results. Include this exact value in the cursor field of subsequent requests. Cursors are temporary and may expire after extended periods.
    - `hasMore` boolean, required — Indicates whether additional results exist beyond this page. When true, use the cursor to fetch the next page. When false, you have reached the end of the result set.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)