Listing keys

Use apis.listKeys to list the keys in a keyspace, up to 100 per page. It’s handy for a “your API keys” screen, for finding every key a user owns, or for auditing a keyspace. It only returns the full key for recoverable keys, and only when you ask. By default, keys are read from a replica, which may not reflect recent changes. Set revalidateKeysCache: true to read keys and their identities from the primary database instead, including when you filter by externalId. Primary reads can have higher latency, depending on your region.

Create a root key with the permissions listed on this page under Root Keys in the dashboard sidebar. CLI commands can instead use a session from unkey login with the required permissions. See Permission reference for every permission.

The root key needs two permissions: api.*.read_key or api.<api_id>.read_key, and api.*.read_api or api.<api_id>.read_api. Adding decrypt: true additionally needs api.*.decrypt_key or api.<api_id>.decrypt_key. See Root key permissions. A missing read permission isn’t a 403. You get HTTP 404 err:unkey:data:api_not_found, “The requested API does not exist or has been deleted.” If you see this for an ID you know is correct, check both permissions on the root key. A key that can read the keys but not decrypt them gets a 403 for decrypt: true that names the missing permission.

Request

string

required

The keyspace to list, by API ID.

integer

default:"100"

Keys per page, 1 to 100.

string

The pagination.cursor from the previous response. Omit for the first page.

string

Only keys linked to the identity with this exact externalId. Use it to list one user’s keys.

boolean

default:"false"

Include plaintext for keys created with recoverable: true. Requires the decrypt permission and a keyspace with encrypted storage enabled. See Recoverable keys.

boolean

default:"false"

Read from the primary database to avoid replica lag. This can increase latency.

curl -X POST https://api.unkey.com/v2/apis.listKeys \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "externalId": "user_123", "limit": 50 }'

Response

data is an array of key objects, and pagination tells you whether to continue.

{
  "meta": { "requestId": "req_..." },
  "data": [
    {
      "keyId": "key_...",
      "start": "sk_prod_abc1",
      "enabled": true,
      "name": "Production key",
      "createdAt": 1704067200000,
      "expires": 1735689600000,
      "meta": { "plan": "premium" },
      "credits": { "remaining": 950 },
      "identity": { "id": "id_...", "externalId": "user_123" }
    }
  ],
  "pagination": { "cursor": "...", "hasMore": true }
}

Each item has the same fields keys.getKey returns. start is the prefix and first few characters, so a user can recognize the key. plaintext appears only when decrypt: true worked for that key. Looking up keys lists every field.

Paging

Send pagination.cursor back until hasMore is false. Cursors expire, so don’t store them.

list-all-keys.ts

let cursor: string | undefined;
do {
  const { data, pagination } = await unkey.apis.listKeys({
    apiId: "api_...",
    externalId: "user_123",
    cursor,
  });
  for (const key of data) {
    console.log(key.keyId, key.start);
  }
  cursor = pagination.hasMore ? pagination.cursor : undefined;
} while (cursor);

In the dashboard

The keyspace’s Keys tab shows the same list. You can filter by key ID, name, identity, and tags (is, contains, starts with, ends with). Select several rows to change their external ID, enable or disable them, or delete them in bulk.

Keys tab with the filter menu open, offering Name, Identity, Key ID, and Tags

Keys tab with two keys selected and the bulk action bar offering Change External ID, Disable key, and Delete key

Get started

Framework guides

Keyspaces

Keys

Rate limiting

Identities

Authorization

Analytics

Developer portal

Security

Cookbook

Request

Response

Paging

In the dashboard