get-identity - Unkey Docs

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

Note

See the API reference for the full HTTP endpoint documentation.

Usage#

unkey api identities get-identity [flags]

Flags#

--identitystringrequired#

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#

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": "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      }    ]  }}