v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB

keys

Get API key

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

post/v2/keys.getKey

Request body

keyIdstring 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.

decryptboolean

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.

Example request

{
  "keyId": "key_1234abcd"
}

Response

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

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "keyId": "key_1234567890abcdef",
    "start": "sk_test_abc123",
    "enabled": true,
    "name": "Production API Key",
    "createdAt": 1701425400000,
    "updatedAt": 1701425400000,
    "lastUsedAt": 1701425400000,
    "expires": 1735689600000,
    "permissions": [
      "documents.read",
      "documents.write"
    ],
    "roles": [
      "editor",
      "viewer"
    ],
    "credits": {
      "remaining": 1000,
      "refill": {
        "interval": "daily",
        "amount": 1000,
        "refillDay": 15
      }
    },
    "identity": {
      "ratelimits": [
        {
          "id": "rl_1234567890abcdef",
          "name": "api_requests",
          "limit": 1000,
          "duration": 3600000,
          "autoApply": true
        }
      ]
    },
    "plaintext": "sk_test_abc123def456",
    "ratelimits": [
      {
        "id": "rl_1234567890abcdef",
        "name": "api_requests",
        "limit": 1000,
        "duration": 3600000,
        "autoApply": true
      }
    ]
  }
}