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 one of 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

Additional permission required for decrypt functionality:

api.*.decrypt_key or api.<api_id>.decrypt_key

POST

apis.listKeys

Go (SDK)

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v3"
	"github.com/unkeyed/sdks/api/go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Apis.ListKeys(ctx, components.V2ApisListKeysRequestBody{
        APIID: "api_1234abcd",
        Cursor: unkey.Pointer("key_1234abcd"),
        ExternalID: unkey.Pointer("user_1234abcd"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2ApisListKeysResponseBody != nil {
        for {
            // handle items

            res, err = res.Next()

            if err != nil {
                // handle error
            }

            if res == nil {
                break
            }
        }
    }
}

from unkey.py import Unkey


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.apis.list_keys(api_id="api_1234abcd", limit=100, cursor="key_1234abcd", external_id="user_1234abcd", decrypt=False, revalidate_keys_cache=False)

    while res is not None:
        # Handle items

        res = res.next()

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

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.apis.listKeys({
    apiId: "api_1234abcd",
    cursor: "key_1234abcd",
    externalId: "user_1234abcd",
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/apis.listKeys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apiId": "api_1234abcd",
  "limit": 100,
  "cursor": "key_1234abcd",
  "externalId": "user_1234abcd",
  "decrypt": false,
  "revalidateKeysCache": false
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    apiId: 'api_1234abcd',
    limit: 100,
    cursor: 'key_1234abcd',
    externalId: 'user_1234abcd',
    decrypt: false,
    revalidateKeysCache: false
  })
};

fetch('https://api.unkey.com/v2/apis.listKeys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/apis.listKeys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'apiId' => 'api_1234abcd',
    'limit' => 100,
    'cursor' => 'key_1234abcd',
    'externalId' => 'user_1234abcd',
    'decrypt' => false,
    'revalidateKeysCache' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/apis.listKeys")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"apiId\": \"api_1234abcd\",\n  \"limit\": 100,\n  \"cursor\": \"key_1234abcd\",\n  \"externalId\": \"user_1234abcd\",\n  \"decrypt\": false,\n  \"revalidateKeysCache\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/apis.listKeys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"apiId\": \"api_1234abcd\",\n  \"limit\": 100,\n  \"cursor\": \"key_1234abcd\",\n  \"externalId\": \"user_1234abcd\",\n  \"decrypt\": false,\n  \"revalidateKeysCache\": false\n}"

response = http.request(request)
puts response.read_body

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "keyId": "key_1234567890abcdef",
      "start": "sk_test_abc123",
      "enabled": true,
      "createdAt": 1701425400000,
      "name": "Production API Key",
      "meta": null,
      "updatedAt": 1701425400000,
      "lastUsedAt": 1701425400000,
      "expires": 1735689600000,
      "permissions": [
        "documents.read",
        "documents.write"
      ],
      "roles": [
        "editor",
        "viewer"
      ],
      "credits": {
        "remaining": 1000,
        "refill": {
          "interval": "daily",
          "amount": 1000,
          "refillDay": 15
        }
      },
      "identity": {
        "id": "<string>",
        "externalId": "<string>",
        "meta": {},
        "ratelimits": [
          {
            "id": "rl_1234567890abcdef",
            "name": "api_requests",
            "limit": 1000,
            "duration": 3600000,
            "autoApply": true
          }
        ]
      },
      "plaintext": "sk_test_abc123def456",
      "ratelimits": [
        {
          "id": "rl_1234567890abcdef",
          "name": "api_requests",
          "limit": 1000,
          "duration": 3600000,
          "autoApply": true
        }
      ]
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ=="
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found",
    "errors": [
      {
        "location": "body.permissions[0].name",
        "message": "Must be at least 3 characters long",
        "fix": "Ensure the name uses only alphanumeric characters, underscores, and hyphens"
      }
    ]
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

Authorizations

Authorization

string

header

required

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs. To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key. Security best practices:

Keep root keys secure and never expose them in client-side code
Use different root keys for different environments
Rotate keys periodically, especially after team member departures
Create keys with minimal necessary permissions following least privilege principle
Monitor key usage with audit logs.

Body

application/json

apiId

string

required

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

Minimum string length: 1

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.

Required range: 1 <= x <= 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.

Minimum string length: 1

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

When true, reads keys and their identities from the primary database to avoid replica lag. When false or omitted, reads from a replica, which may not reflect recent changes. Primary reads can have higher latency, depending on your region.

Response

Successfully retrieved paginated keys. Use the pagination cursor for additional results when hasMore: true.

meta

object

required

Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The requestId is particularly important when troubleshooting issues with the Unkey support team.

Show child attributes

data

object[]

required

Array of API keys with complete configuration and metadata.

Maximum array length: 100

Show child attributes

pagination

object

required

Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.

Show child attributes

⌘I

Go (SDK)

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v3"
	"github.com/unkeyed/sdks/api/go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Apis.ListKeys(ctx, components.V2ApisListKeysRequestBody{
        APIID: "api_1234abcd",
        Cursor: unkey.Pointer("key_1234abcd"),
        ExternalID: unkey.Pointer("user_1234abcd"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2ApisListKeysResponseBody != nil {
        for {
            // handle items

            res, err = res.Next()

            if err != nil {
                // handle error
            }

            if res == nil {
                break
            }
        }
    }
}

from unkey.py import Unkey


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.apis.list_keys(api_id="api_1234abcd", limit=100, cursor="key_1234abcd", external_id="user_1234abcd", decrypt=False, revalidate_keys_cache=False)

    while res is not None:
        # Handle items

        res = res.next()

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

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.apis.listKeys({
    apiId: "api_1234abcd",
    cursor: "key_1234abcd",
    externalId: "user_1234abcd",
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/apis.listKeys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apiId": "api_1234abcd",
  "limit": 100,
  "cursor": "key_1234abcd",
  "externalId": "user_1234abcd",
  "decrypt": false,
  "revalidateKeysCache": false
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    apiId: 'api_1234abcd',
    limit: 100,
    cursor: 'key_1234abcd',
    externalId: 'user_1234abcd',
    decrypt: false,
    revalidateKeysCache: false
  })
};

fetch('https://api.unkey.com/v2/apis.listKeys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/apis.listKeys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'apiId' => 'api_1234abcd',
    'limit' => 100,
    'cursor' => 'key_1234abcd',
    'externalId' => 'user_1234abcd',
    'decrypt' => false,
    'revalidateKeysCache' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/apis.listKeys")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"apiId\": \"api_1234abcd\",\n  \"limit\": 100,\n  \"cursor\": \"key_1234abcd\",\n  \"externalId\": \"user_1234abcd\",\n  \"decrypt\": false,\n  \"revalidateKeysCache\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/apis.listKeys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"apiId\": \"api_1234abcd\",\n  \"limit\": 100,\n  \"cursor\": \"key_1234abcd\",\n  \"externalId\": \"user_1234abcd\",\n  \"decrypt\": false,\n  \"revalidateKeysCache\": false\n}"

response = http.request(request)
puts response.read_body

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "keyId": "key_1234567890abcdef",
      "start": "sk_test_abc123",
      "enabled": true,
      "createdAt": 1701425400000,
      "name": "Production API Key",
      "meta": null,
      "updatedAt": 1701425400000,
      "lastUsedAt": 1701425400000,
      "expires": 1735689600000,
      "permissions": [
        "documents.read",
        "documents.write"
      ],
      "roles": [
        "editor",
        "viewer"
      ],
      "credits": {
        "remaining": 1000,
        "refill": {
          "interval": "daily",
          "amount": 1000,
          "refillDay": 15
        }
      },
      "identity": {
        "id": "<string>",
        "externalId": "<string>",
        "meta": {},
        "ratelimits": [
          {
            "id": "rl_1234567890abcdef",
            "name": "api_requests",
            "limit": 1000,
            "duration": 3600000,
            "autoApply": true
          }
        ]
      },
      "plaintext": "sk_test_abc123def456",
      "ratelimits": [
        {
          "id": "rl_1234567890abcdef",
          "name": "api_requests",
          "limit": 1000,
          "duration": 3600000,
          "autoApply": true
        }
      ]
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ=="
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found",
    "errors": [
      {
        "location": "body.permissions[0].name",
        "message": "Must be at least 3 characters long",
        "fix": "Ensure the name uses only alphanumeric characters, underscores, and hyphens"
      }
    ]
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

APIs

Keys

Identities

Permissions

Rate limiting

Analytics

Portal

List API keys

Authorizations

Body

Response