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

# Get API key

`POST /v2/keys.getKey`

Retrieve detailed key information for dashboard interfaces and administrative purposes.

Use this to build key management dashboards showing users their key details, status, permissions, and usage data. You can identify keys by `keyId` or the actual key string.

**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.

**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)

Additional permission required for decrypt functionality:
- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#decrypt_key`

## Request body

- V2KeysGetKeyRequestBody
  - `keyId` string, required — Specifies which key to retrieve using the database identifier returned from `keys.createKey`. Do not confuse this with the actual API key string that users include in requests. Key data includes metadata, permissions, usage statistics, and configuration but never the plaintext key value unless `decrypt=true`. Find this ID in creation responses, key listings, dashboard, or verification responses.
  - `decrypt` boolean — Controls whether to include the plaintext key value in the response for recovery purposes. Only works for keys created with `recoverable=true` and requires the `decrypt_key` permission. Returned keys must be handled securely, never logged, cached, or stored insecurely. Use only for legitimate recovery scenarios like user password resets or emergency access. Most applications should keep this false to maintain security best practices and avoid accidental key exposure. Decryption requests are audited and may trigger security alerts in enterprise environments.

## Response `200`

Successfully retrieved key information. When `decrypt: true`, includes plaintext key value for recoverable keys.

- V2KeysGetKeyResponseBody
  - `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/4bd11a7252bc/schema)