Skip to main content
Look up a key’s settings without verifying it or spending anything. Use 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.
Create a root key with the permissions listed on this page under Root Keys in the dashboard sidebar. CLI commands can instead use a session from unkey login with the required permissions. See Permission reference for every permission.
Both endpoints need 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.
A key that doesn’t exist, is deleted, or belongs to another workspace returns HTTP 404 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.
To page through many keys at once, use apis.listKeys, which returns the same objects. See Listing keys.
Last modified on October 6, 2026