keys.getKey when you have the key’s ID, for example on a management screen. Use keys.whoami when you have the key itself, for example when a user pastes it into a support form. Both return the same fields, except keys.whoami can’t return the decrypted key.
You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys, and pass it as
Authorization: Bearer <root key>. See Permission reference for every permission.api.*.read_key or api.<api_id>.read_key. Adding decrypt: true to keys.getKey additionally needs api.*.decrypt_key or api.<api_id>.decrypt_key. See Root key permissions.
By identifier
string
required
The
key_... identifier from keys.createKey, a verification response, a listing, or the dashboard. 3 to 255 characters matching ^[a-zA-Z0-9_]+$.boolean
default:"false"
Include the plaintext for a key created as recoverable. See Recoverable keys.
err:unkey:data:key_not_found.
By plaintext
string
required
The full key including its prefix, 1 to 512 characters. Any change to it gives a not-found error.
keys.whoami doesn’t check whether the key is enabled, expired, or within its limits, and it doesn’t record a verification. Use keys.verifyKey when you need a verdict.
Response fields
string
required
The key’s identifier.
string
required
The prefix and first characters of the key, for display in lists.
boolean
required
Whether the key is enabled.
integer
required
Creation time as Unix milliseconds.
integer
Last update as Unix milliseconds, when the key has been updated.
integer
Last successful verification as Unix milliseconds. It updates about once a minute, so it can lag real usage by up to a minute.
string
The internal name.
object
The key’s metadata.
integer
Expiry as Unix milliseconds, when set.
object
remaining (integer or null for unlimited) and, when configured, refill with interval, amount, and refillDay.object[]
Each key-level rate limit:
id, name, limit, duration, autoApply.string[]
Permission slugs the key holds directly or through roles.
string[]
Role names assigned to the key.
object
When linked:
id, externalId, the identity’s meta, and its ratelimits.string
The decrypted key. Returned only by
keys.getKey with decrypt: true on a recoverable key. keys.whoami never returns it.apis.listKeys, which returns the same objects. See Listing keys.