---
title: "List Identities"
method: POST
path: "/v2/identities.listIdentities"
tags: ["identities"]
---

# List Identities

`POST /v2/identities.listIdentities`

Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations.

Perfect for building management dashboards, auditing configurations, or browsing your identities.

> **Important**
> Requires `identity.*.read_identity` permission

## Request body

- V2IdentitiesListIdentitiesRequestBody
  - `limit` integer — The maximum number of identities to return in a single request. Use this to control response size and loading performance.
  - `cursor` string — Pagination cursor from a previous response. Use this to fetch subsequent pages of results when the response contains a cursor value.
  - `search` string — Free-form text to filter identities. Returns identities whose ID or external ID contains the search string. Matching is case-insensitive.

## Response `200`

Successfully retrieved the list of identities

- V2IdentitiesListIdentitiesResponseBody
  - `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` Identity[], required — List of identities matching the specified criteria.
    - `id` string, required — Identity ID
    - `externalId` string, required — External identity ID
    - `meta` object — Identity metadata
    - `ratelimits` RatelimitResponse[] — Identity ratelimits
      - `id` string, required — Unique identifier for this rate limit configuration.
      - `name` string, required — Human-readable name for this rate limit.
      - `limit` integer, required — Maximum requests allowed within the time window.
      - `duration` integer, required — Rate limit window duration in milliseconds.
      - `autoApply` boolean, required — Whether this rate limit was automatically applied when verifying the 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` — Bad Request - Invalid parameters
- `401` — Unauthorized - Missing or invalid authentication
- `403` — Forbidden - Insufficient permissions (requires `identity.*.read_identity`)
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)