list-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:

api.*.read_key or api.<api_id>.read_key (to read keys)
api.*.read_api or api.<api_id>.read_api (to read the API)
api.*.decrypt_key or api.<api_id>.decrypt_key (additionally required when using --decrypt)

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api apis list-keys [flags]

Flags

string

required

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

integer

default:100

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

string

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

string

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

boolean

default:false

When true, includes the plaintext key value in the response. Only works for keys created with recoverable: true. Requires the decrypt_key permission on the calling root key. Never enable this in user-facing applications.

boolean

default:false

Experimental. Skip the cache and fetch keys directly from the database. Use this when you have just created a key and need to see it immediately, or when debugging cache consistency issues. This comes with a performance cost and should be used sparingly.

Global Flags

Flag	Type	Description
`--root-key`	string	Override root key (`$UNKEY_ROOT_KEY`)
`--api-url`	string	Override API base URL (default: `https://api.unkey.com`)
`--config`	string	Path to config file (default: `~/.unkey/config.toml`)
`--output`	string	Output format. Use `json` for raw JSON
`--body`	string	Send this JSON string as the request body. You cannot combine it with request-building flags.

Examples

unkey api apis list-keys --api-id=api_1234abcd

unkey api apis list-keys --api-id=api_1234abcd --limit=50

unkey api apis list-keys --api-id=api_1234abcd --external-id=user_1234abcd

CURSOR=""
while true; do
  RESULT=$(unkey api apis list-keys --api-id=api_1234abcd --limit=100 --output=json ${CURSOR:+--cursor=$CURSOR})
  echo "$RESULT" | jq '.data[]'
  HAS_MORE=$(echo "$RESULT" | jq -r '.pagination.hasMore')
  [ "$HAS_MORE" != "true" ] && break
  CURSOR=$(echo "$RESULT" | jq -r '.pagination.cursor')
done

Output

Default output shows the request ID, followed by the list of keys:

req_1234abcd

[
  {
    "keyId": "key_1234abcd",
    "start": "sk_prod",
    "enabled": true,
    "name": "Production API Key",
    "createdAt": 1704067200000
  },
  {
    "keyId": "key_5678efgh",
    "start": "sk_dev",
    "enabled": true,
    "name": "Development Key",
    "createdAt": 1704153600000
  }
]

With --output=json, the full response envelope including pagination is returned:

{
  "meta": {
    "requestId": "req_1234abcd"
  },
  "data": [
    {
      "keyId": "key_1234abcd",
      "start": "sk_prod",
      "enabled": true,
      "name": "Production API Key",
      "createdAt": 1704067200000
    }
  ],
  "pagination": {
    "cursor": "key_1234abcd",
    "hasMore": true
  }
}

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Usage

Flags

Global Flags

Examples

Output

​Usage

​Flags

​Global Flags

​Examples

​Output

Usage

Flags

Global Flags

Examples

Output