Skip to main content
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 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
For decrypt functionality:
  • api.*.decrypt_key or api.<api_id>.decrypt_key

​
Request

​
apiId
string
required
The API namespace whose keys you want to list. Returns all keys in this API, subject to pagination and filters.Example: api_1234abcd
​
limit
integer
default:"100"
Maximum number of keys to return per request. Balance between response size and number of pagination calls needed.Range: 1-100
​
cursor
string
Pagination cursor from previous response to fetch next page. Use when hasMore: true in previous response.Example: key_1234abcd
​
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.Example: user_1234abcd
​
decrypt
boolean
default:"false"
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
default:"false"
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

​
data
array
required
Array of API keys with complete configuration and metadata.
​
keyId
string
The unique identifier for this key in Unkey’s system.
​
start
string
The first few characters of the key for identification purposes (includes prefix).
​
plaintext
string
The complete plaintext key value. Only present when decrypt: true and key was created with recoverable: true.
​
enabled
boolean
Whether the key is currently active.
​
name
string
Human-readable name assigned to the key.
​
createdAt
integer
Unix timestamp in milliseconds when the key was created.
​
expires
integer
Unix timestamp in milliseconds when the key expires. Omitted for permanent keys.
​
meta
object
Custom metadata associated with the key.
​
permissions
array
List of permissions directly assigned to the key.
​
roles
array
List of roles assigned to the key.
​
credits
object
Credit configuration for the key.
​
remaining
integer
Current number of credits available.
​
refill
object
Automatic refill configuration.
​
amount
integer
Number of credits added on each refill.
​
interval
string
Refill frequency: daily or monthly.
​
refillDay
integer
Day of month for monthly refills (1-31).
​
identity
object
Information about the identity associated with this key.
​
externalId
string
The external identifier from your system.
​
meta
object
Custom metadata associated with the identity.
​
pagination
object
Pagination information for navigating through results.
​
cursor
string
Token for requesting the next page. Pass this as the cursor parameter in the next request.
​
hasMore
boolean
Whether more results are available beyond the current page.

​
Examples

curl -X POST https://api.unkey.com/v2/apis.listKeys \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_1234abcd"
  }'

​
Filter by User

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

​
Pagination

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ token: process.env.UNKEY_ROOT_KEY });

let cursor: string | undefined = undefined;
const allKeys = [];

do {
  const { result } = await unkey.apis.listKeys({
    apiId: "api_1234abcd",
    limit: 100,
    cursor,
  });
  
  allKeys.push(...result.keys);
  cursor = result.cursor;
} while (cursor);

console.log(`Total keys: ${allKeys.length}`);

​
Response Examples

​
Basic Key List

{
  "meta": {
    "requestId": "req_1234abcd"
  },
  "data": [
    {
      "keyId": "key_1234abcd",
      "start": "sk_prod",
      "enabled": true,
      "name": "Production API Key",
      "createdAt": 1704067200000,
      "expires": 1735689600000,
      "meta": {
        "plan": "premium",
        "userId": "user_5678",
        "environment": "production"
      },
      "permissions": ["documents.read", "documents.write"],
      "roles": ["editor"],
      "credits": {
        "remaining": 8500,
        "refill": {
          "amount": 10000,
          "interval": "monthly",
          "refillDay": 1
        }
      },
      "identity": {
        "externalId": "user_5678",
        "meta": {
          "plan": "premium",
          "signupDate": "2024-01-15"
        }
      }
    },
    {
      "keyId": "key_5678efgh",
      "start": "sk_dev",
      "enabled": true,
      "name": "Development Key",
      "createdAt": 1704153600000,
      "meta": {
        "environment": "development"
      },
      "permissions": ["documents.read"],
      "credits": {
        "remaining": 500
      }
    }
  ],
  "pagination": {
    "cursor": "key_5678efgh",
    "hasMore": false
  }
}

​
Empty Response

{
  "meta": {
    "requestId": "req_9876zyxw"
  },
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false
  }
}

​
With Decrypted Keys

{
  "meta": {
    "requestId": "req_admin_decrypt"
  },
  "data": [
    {
      "keyId": "key_admin_123",
      "start": "sk_admin",
      "plaintext": "sk_admin_1234abcdef5678",
      "enabled": true,
      "name": "Admin Recovery Key",
      "createdAt": 1704067200000,
      "permissions": ["admin.all"],
      "meta": {
        "recoverable": true,
        "purpose": "emergency_access"
      }
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us