list-identities

List all identities in your Unkey workspace using the CLI. Retrieve paginated results with metadata and linked key counts for each entity.

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.

Required permissions:

• identity.*.read_identity (to list identities in your workspace)

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api identities list-identities [flags]

Flags

--limit · integer

The maximum number of identities to return in a single request. Use this to control response size and loading performance. Must be between 1 and 100. Defaults to 100.

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

Global Flags

Flag	Type	Description
--root-key	string	Override root key ($UNKEY_ROOT_KEY)
--api-url	string	Override API base URL (default: https://api.unkey.com)
--config	string	Path to config file (default: ~/.unkey/config.toml)
--output	string	Output format. Use json for raw JSON
--body	string	Send this JSON string as the request body. You cannot combine it with request-building flags.

Examples

Basic

unkey api identities list-identities

Output

Default output shows the request ID, followed by the list of identities:

req_01H9TQPP77V5E48E9SH0BG0ZQX

{
  "identities": [
    {
      "id": "id_01H9TQP8NP8JN3X8HWSKPW43JE",
      "externalId": "user_123",
      "meta": {
        "name": "Alice Smith",
        "plan": "premium"
      },
      "ratelimits": [
        {
          "name": "requests",
          "limit": 1000,
          "duration": 60000
        }
      ]
    },
    {
      "id": "id_02ZYR3Q9NP8JM4X8HWSKPW43JF",
      "externalId": "user_456",
      "meta": {
        "name": "Bob Johnson",
        "plan": "basic"
      },
      "ratelimits": [
        {
          "name": "requests",
          "limit": 500,
          "duration": 60000
        }
      ]
    }
  ],
  "cursor": "cursor_eyJsYXN0SWQiOiJpZF8wMlpZUjNROU5QOEpNNFg4SFdTS1BXNDNKRiJ9",
  "total": 247
}

With --output=json, the full response envelope is returned:

{
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQX"
  },
  "data": {
    "identities": [
      {
        "id": "id_01H9TQP8NP8JN3X8HWSKPW43JE",
        "externalId": "user_123",
        "meta": {
          "name": "Alice Smith",
          "plan": "premium"
        },
        "ratelimits": [
          {
            "name": "requests",
            "limit": 1000,
            "duration": 60000
          }
        ]
      }
    ],
    "cursor": "cursor_eyJsYXN0SWQiOiJpZF8wMlpZUjNROU5QOEpNNFg4SFdTS1BXNDNKRiJ9",
    "total": 247
  }
}