---
title: "Get Identity"
method: POST
path: "/v2/identities.getIdentity"
tags: ["identities"]
---

# Get Identity

`POST /v2/identities.getIdentity`

Retrieve an identity by external ID. Returns metadata, rate limits, and other associated data.

Use this to check if an identity exists, view configurations, or build management dashboards.

> **Important**
> Requires `identity.*.read_identity` permission

## Request body

- V2IdentitiesGetIdentityRequestBody
  - `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).

## Response `200`

Successfully retrieved the identity information

- V2IdentitiesGetIdentityResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` Identity, required
    - `id` string, required — Identity ID
    - `externalId` string, required — External identity ID
    - `meta` object — Identity metadata
    - `ratelimits` RatelimitResponse[] — Identity ratelimits
      - `id` string, required — Unique identifier for this rate limit configuration.
      - `name` string, required — Human-readable name for this rate limit.
      - `limit` integer, required — Maximum requests allowed within the time window.
      - `duration` integer, required — Rate limit window duration in milliseconds.
      - `autoApply` boolean, required — Whether this rate limit was automatically applied when verifying the key.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `identity.*.read_identity`)
- `404` — Not Found - Identity with the specified externalId doesn't exist
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/9bbd42d710cf/schema)