Skip to main content
Retrieve an identity by external ID or internal identity ID. Returns metadata, rate limits, and other associated data. Use this to check if an identity exists, view configurations, or build management dashboards. Required permissions:
  • identity.*.read_identity
See the API reference for the full HTTP endpoint documentation.

​
Usage

unkey api identities get-identity [flags]

​
Flags

​
--identity
string
required
The ID of the identity to retrieve. This can be either the externalId (from your own system that was used during identity creation) or the identityId (the internal ID returned by the identity service).

​
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 get-identity --identity=user_123

​
Output

Default output shows the request ID with latency, followed by the identity: 
req_01H9TQPP77V5E48E9SH0BG0ZQX (took 32ms)

{
  "id": "id_1234567890abcdef",
  "externalId": "user_123",
  "meta": {
    "name": "Alice Smith",
    "email": "alice@acme.com",
    "plan": "premium"
  },
  "ratelimits": [
    {
      "name": "requests",
      "limit": 1000,
      "duration": 60000
    }
  ]
}
With --output=json, the full response envelope is returned: 
{
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQX"
  },
  "data": {
    "id": "id_1234567890abcdef",
    "externalId": "user_123",
    "meta": {
      "name": "Alice Smith",
      "email": "alice@acme.com",
      "plan": "premium"
    },
    "ratelimits": [
      {
        "name": "requests",
        "limit": 1000,
        "duration": 60000
      }
    ]
  }
}
Last modified on March 26, 2026