Skip to main content
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 root key 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)
Additional permission required for decrypt functionality:
  • api.*.decrypt_key or api.<api_id>.decrypt_key

​
Request

​
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.Pattern: ^[a-zA-Z0-9_]+$Example: key_1234abcd
​
decrypt
boolean
default:"false"
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

​
keyId
string
required
The unique identifier for this key in Unkey’s system.
​
start
string
The prefix of the key for visual identification.
​
enabled
boolean
Whether the key is currently active.
​
name
string
Human-readable name for the key.
​
plaintext
string
The full plaintext key value (only when decrypt=true and key is recoverable).
​
createdAt
integer
Unix timestamp in milliseconds when the key was created.
​
expires
integer
Unix timestamp in milliseconds when the key expires (if set).
​
meta
object
Custom metadata attached to the key.
​
permissions
array
Array of permission strings assigned to the key.
​
roles
array
Array of role names assigned to the key.
​
credits
object
Credit balance and refill configuration.
​
remaining
integer
Current credit balance.
​
refill
object
Automatic refill settings.
​
ratelimits
array
Array of rate limit configurations attached to the key.
​
identity
object
Identity information if the key is associated with an identity.

​
Examples

curl -X POST https://api.unkey.com/v2/keys.getKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_1234abcd"
  }'

​
With Decryption

curl -X POST https://api.unkey.com/v2/keys.getKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_5678efgh",
    "decrypt": true
  }'

​
Response Example

{
  "meta": {
    "requestId": "req_1234abcd"
  },
  "data": {
    "keyId": "key_1234abcd",
    "start": "sk_prod",
    "enabled": true,
    "name": "Production API Key",
    "createdAt": 1704067200000,
    "expires": 1735689600000,
    "meta": {
      "plan": "premium",
      "userId": "user_5678",
      "environment": "production"
    },
    "permissions": [
      "documents.read",
      "documents.write"
    ],
    "roles": [
      "editor"
    ],
    "credits": {
      "remaining": 8500,
      "refill": {
        "amount": 10000,
        "interval": "monthly",
        "refillDay": 1
      }
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us