---
title: "List root keys"
method: POST
path: "/v2/rootKeys.listKeys"
tags: ["rootKeys"]
---

# List root keys

`POST /v2/rootKeys.listKeys`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/rootKeys.listKeys`
- Auth: HTTP bearer

Lists readable root keys in the authenticated workspace, ordered by key ID.
Requires `unkey:v1:<workspace_id>:rootKeys/<key_id>#read` for each returned key.
Use `rootKeys/*#read` to read all root keys. Write permission does not imply read.
A caller with no readable keys receives an empty page.

Includes disabled and expired keys from the new root-key store.
Deleted keys are excluded. Secrets and hashes are never returned.
Pass the returned cursor when hasMore is true to retrieve the next page.

## Request body

- V2RootKeysListKeysRequestBody
  - `limit` integer: Maximum number of readable root keys per page.
  - `cursor` string: Opaque cursor from a previous response. Omit for the first page.

## Response `200`

A page of readable root keys.

- V2RootKeysListKeysResponseBody
  - `meta` Meta, 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.
    - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2RootKeysListKeysResponseData[], required
    - `ipAllowlist` string[], required: Allowed IPv4 or IPv6 addresses and CIDR ranges. An empty list allows any IP address.
    - `keyId` string, required: Stable root key identifier.
    - `name` string, nullable, required: User-supplied name, or null when absent.
    - `start` string, required: Stored display fragment, including the prefix when present.
    - `end` string, required: Stored trailing display fragment. Empty for keys without a recorded suffix.
    - `enabled` boolean, required: Whether the key is administratively enabled. An enabled key can still be expired.
    - `createdAt` integer, required: Creation time in Unix milliseconds.
    - `lastUsedAt` integer, required: Last verification time in Unix milliseconds. Zero means the root key has not been used.
    - `expires` integer, nullable, required: Expiration time in Unix milliseconds, or null for no expiration.
    - `permissions` string[], required: All permissions assigned to the root key.
  - `pagination` Pagination, required: Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
    - `cursor` string: Opaque pagination token for retrieving the next page of results. Include this exact value in the cursor field of subsequent requests. Cursors are temporary and may expire after extended periods.
    - `hasMore` boolean, required: Indicates whether additional results exist beyond this page. When true, use the cursor to fetch the next page. When false, you have reached the end of the result set.

## Other responses

- `400`: Invalid request.
- `401`: Authentication is required.
- `429`: Too many requests.
- `500`: The list could not be loaded.

## Changes

- **2026-10-31** `88bb238417d8`: 1 info
  - added the required property `data/items/ipAllowlist` to the response with the `200` status
- **2026-09-30** `2cf3cf769b2e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/rootKeys.listKeys/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)