Skip to main content
Unkey Docs

list-keys

List all API keys in a namespace with the Unkey CLI. Retrieve paginated results including key IDs, metadata, and status for admin scripts.
2 min read

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)
Note

See the API reference for the full HTTP endpoint documentation.

Usage#

Flags#

--api-idstringrequired#

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. Must be between 1 and 100.

Default: 100

--cursorstring#

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

--external-idstring#

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, 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.

Default: false

--revalidate-keys-cacheboolean#

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.

Default: false

Global Flags#

FlagTypeDescription
--root-keystringOverride root key ($UNKEY_ROOT_KEY)
--api-urlstringOverride API base URL (default: https://api.unkey.com)
--configstringPath to config file (default: ~/.unkey/config.toml)
--outputstringOutput format. Use json for raw JSON
--bodystringSend this JSON string as the request body. You cannot combine it with request-building flags.

Examples#

Output#

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

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

get-apicreate-project