---
title: "Get API key by hash"
method: POST
path: "/v2/keys.whoami"
tags: ["keys"]
---

# Get API key by hash

`POST /v2/keys.whoami`

Find out what key this is.

**Required Permissions**

Your credential must have one of the following permissions for basic key information:
- `api.*.read_key` (to read keys from any API)
- `api.<api_id>.read_key` (to read keys from a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)

If your credential lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existence of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your credential has the correct permissions.

## Request body

- V2KeysWhoamiRequestBody
  - `key` string, required — The complete API key string provided by you, including any prefix. Never log, cache, or store API keys in your system as they provide full access to user resources. Include the full key exactly as provided - even minor modifications will cause a not found error.

## Response `200`

Successfully retrieved key information.

- V2KeysWhoamiResponseBody
  - `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` KeyResponseData, required
    - `keyId` string, required — Unique identifier for this key.
    - `start` string, required — First few characters of the key for identification.
    - `enabled` boolean, required — Whether the key is enabled or disabled.
    - `name` string — Human-readable name for this key.
    - `meta` object — Custom metadata associated with this key.
    - `createdAt` integer, required — Unix timestamp in milliseconds when key was created.
    - `updatedAt` integer — Unix timestamp in milliseconds when key was last updated.
    - `lastUsedAt` integer — Unix timestamp in milliseconds when key was last used for verification. This is an approximated value, accurate to within 5 minutes.
    - `expires` integer — Unix timestamp in milliseconds when key expires (if set).
    - `permissions` string[]
    - `roles` string[]
    - `credits` KeyCreditsData — Credit configuration and remaining balance for this key.
      - `remaining` integer, nullable, required — Number of credits remaining (null for unlimited).
      - `refill` KeyCreditsRefill — Configuration for automatic credit refill behavior.
        - `interval` 'daily' | 'monthly', required — How often credits are automatically refilled.
        - `amount` integer, required — Number of credits to add during each refill cycle.
        - `refillDay` integer — Day of the month for monthly refills (1-31). Only required when interval is 'monthly'. For days beyond the month's length, refill occurs on the last day of the month.
    - `identity` Identity
      - `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.
    - `plaintext` string — Decrypted key value (only when decrypt=true).
    - `ratelimits` RatelimitResponse[]
      - `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
- `404` — Not found
- `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/d3689bca6458/schema)