get-identity

Retrieve an identity by external ID or internal ID using the Unkey CLI. View associated metadata, rate limits, and linked API key details.

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

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

Basic

unkey api identities get-identity --identity=user_123

Output

Default output shows the request ID, followed by the identity:

req_01H9TQPP77V5E48E9SH0BG0ZQX

{
  "id": "id_1234567890abcdef",
  "externalId": "user_123",
  "meta": {
    "name": "Alice Smith",
    "email": "[e-mail]",
    "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": "[e-mail]",
      "plan": "premium"
    },
    "ratelimits": [
      {
        "name": "requests",
        "limit": 1000,
        "duration": 60000
      }
    ]
  }
}