Skip to main content

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

​
Required Permissions

Requires identity.*.read_identity permission

​
Request

​
limit
integer
Maximum number of identities to return per request.Example: 50
​
cursor
string
Pagination cursor from previous response to fetch next page.Example: cursor_eyJrZXkiOiJrZXlfMTIzNCJ9

​
Response

​
identities
array
required
Array of identity objects. Each identity includes:
  • id - Internal identity identifier
  • externalId - Your system’s identifier
  • meta - Custom metadata object
  • ratelimits - Array of rate limit configurations
​
cursor
string
Pagination cursor for fetching the next page (null if no more results).
​
total
integer
Total number of identities in the workspace.

​
Example

cURL
curl -X POST https://api.unkey.com/v2/identities.listIdentities \
  -H "Authorization: Bearer <your-root-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50
  }'
Response
{
  "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
          }
        ]
      },
      {
        "id": "id_02ZYR3Q9NP8JM4X8HWSKPW43JF",
        "externalId": "user_456",
        "meta": {
          "name": "Bob Johnson",
          "plan": "basic"
        },
        "ratelimits": [
          {
            "name": "requests",
            "limit": 500,
            "duration": 60000
          }
        ]
      }
    ],
    "cursor": "cursor_eyJsYXN0SWQiOiJpZF8wMlpZUjNROU5QOEpNNFg4SFdTS1BXNDNKRiJ9",
    "total": 247
  }
}

​
Error Codes

  • 400 - Bad request (invalid parameters)
  • 401 - Unauthorized (missing or invalid root key)
  • 403 - Forbidden (insufficient permissions - requires identity.*.read_identity)
  • 429 - Too many requests (rate limit exceeded)
  • 500 - Internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us