Skip to main content

Documentation Index

Fetch the complete documentation index at: https://unkey.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 May 6, 2026