List API 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

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

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

integer

default:"100"

Maximum number of keys to return per request. Balance between response size and number of pagination calls needed.Range: 1-100

string

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

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

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

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

array

required

Array of API keys with complete configuration and metadata.

string

The unique identifier for this key in Unkey’s system.

string

The first few characters of the key for identification purposes (includes prefix).

string

The complete plaintext key value. Only present when decrypt: true and key was created with recoverable: true.

boolean

Whether the key is currently active.

string

Human-readable name assigned to the key.

integer

Unix timestamp in milliseconds when the key was created.

integer

Unix timestamp in milliseconds when the key expires. Omitted for permanent keys.

object

Custom metadata associated with the key.

array

List of permissions directly assigned to the key.

array

List of roles assigned to the key.

object

Credit configuration for the key.

integer

Current number of credits available.

object

Automatic refill configuration.

integer

Number of credits added on each refill.

string

Refill frequency: daily or monthly.

integer

Day of month for monthly refills (1-31).

object

Information about the identity associated with this key.

string

The external identifier from your system.

object

Custom metadata associated with the identity.

object

Pagination information for navigating through results.

string

Token for requesting the next page. Pass this as the cursor parameter in the next request.

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"
  }'

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

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

const { result } = await unkey.apis.listKeys({
  apiId: "api_1234abcd",
});

for (const key of result.keys) {
  console.log(`${key.name}: ${key.start}`);
  console.log(`  Enabled: ${key.enabled}`);
  console.log(`  Credits: ${key.credits?.remaining}`);
}

if (result.cursor) {
  console.log("More keys available");
}

import os
import requests

response = requests.post(
    "https://api.unkey.com/v2/apis.listKeys",
    headers={
        "Authorization": f"Bearer {os.environ['UNKEY_ROOT_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "apiId": "api_1234abcd"
    }
)

result = response.json()
for key in result["data"]:
    print(f"{key['name']}: {key['start']}")
    print(f"  Enabled: {key['enabled']}")
    if "credits" in key:
        print(f"  Credits: {key['credits']['remaining']}")

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/unkeyed/unkey-go"
	"github.com/unkeyed/unkey-go/models/components"
)

func main() {
	uk := unkey.New(
		unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
	)

	ctx := context.Background()
	res, err := uk.Apis.ListKeys(ctx, &components.V2ApisListKeysRequestBody{
		ApiID: "api_1234abcd",
	})

	if err != nil {
		panic(err)
	}

	for _, key := range res.Data {
		fmt.Printf("%s: %s\n", *key.Name, *key.Start)
		fmt.Printf("  Enabled: %t\n", key.Enabled)
	}
}

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
  }'

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

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

const { result } = await unkey.apis.listKeys({
  apiId: "api_1234abcd",
  externalId: "user_1234abcd",
  limit: 50,
});

console.log(`Found ${result.keys.length} keys for user`);

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}`);

import os
import requests

all_keys = []
cursor = None

while True:
    payload = {"apiId": "api_1234abcd", "limit": 100}
    if cursor:
        payload["cursor"] = cursor
    
    response = requests.post(
        "https://api.unkey.com/v2/apis.listKeys",
        headers={
            "Authorization": f"Bearer {os.environ['UNKEY_ROOT_KEY']}",
            "Content-Type": "application/json"
        },
        json=payload
    )
    
    result = response.json()
    all_keys.extend(result["data"])
    
    if not result.get("pagination", {}).get("hasMore"):
        break
    
    cursor = result["pagination"]["cursor"]

print(f"Total keys: {len(all_keys)}")

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
  }
}

Overview

Keys

APIs

Rate Limiting

Identities

Analytics

Permissions

List API Keys

Required Permissions

Request

Response

Examples

Filter by User

Response Examples

Basic Key List

Empty Response

With Decrypted Keys

​Required Permissions

​Request

​Response

​Examples

​Filter by User

​Pagination

​Response Examples

​Basic Key List

​Empty Response

​With Decrypted Keys

Required Permissions

Request

Response

Examples

Filter by User

Pagination

Response Examples

Basic Key List

Empty Response

With Decrypted Keys