list-identities - Unkey Docs

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)

Note

See the API reference for the full HTTP endpoint documentation.

Usage#

unkey api identities list-identities [flags]

Flags#

--limitinteger#

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.

--cursorstring#

Pagination cursor from a previous response. Use this to fetch subsequent pages of results when the response contains a cursor value.

--searchstring#

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#

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