Skip to main content
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.

​
Global Flags

FlagTypeDescription
--root-keystringOverride root key ($UNKEY_ROOT_KEY)
--api-urlstringOverride API base URL (default: https://api.unkey.com)
--configstringPath to config file (default: ~/.unkey/config.toml)
--outputstringOutput format — use json for raw JSON

​
Examples

unkey api identities list-identities

​
Output

Default output shows the request ID with latency, followed by the list of identities: 
req_01H9TQPP77V5E48E9SH0BG0ZQX (took 120ms)

{
  "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
  }
}
Last modified on March 26, 2026