Skip to main content
A key is the credential your users include in API requests to authenticate with your service. Unkey manages the full lifecycle: creation, verification, rotation, and revocation. Unkey never stores keys in plain text. On creation, the key is returned once and only its SHA-256 hash is persisted. Verification works by hashing the incoming key and comparing hashes.

​
Key lifecycle

​
Create a key

Keys are created through the API, SDK, or dashboard. Each key requires an apiId to associate it with a keyspace. On creation, you can configure: The response includes the full key value. This is the only time the plaintext key is available. Store it securely or deliver it to your user immediately.

​
Verify a key

Verification checks the key’s validity and enforces all attached policies in a single call. Unkey evaluates the following checks in order:
  1. Existence. The key hash must match a record in the keyspace.
  2. Enabled. The key must not be disabled.
  3. Expiration. The key must not have passed its expiration timestamp.
  4. Credits. If remaining credits are configured, at least one credit must be available. Verification deducts one credit.
  5. Rate limits. All rate limit configurations on the key are evaluated. If any limit is exceeded, the request is rejected.
  6. Permissions. If you pass a permission query, the key must satisfy it.
The response includes:

​
Features

Each key can carry several optional features:

​
Rotate a key

Rotation creates a new key and revokes the old one. The new key inherits the same configuration (metadata, limits, permissions) but has a new value and key ID. See Rerolling keys for details.

​
Revoke a key

Revoking a key permanently deletes it. Revoked keys can’t be restored. If you need to temporarily block a key, disable it instead. See Revocation for details.

​
Key storage

By default, Unkey stores only the SHA-256 hash of each key. The plaintext is returned once at creation and never stored. If the keyspace has Store encrypted keys enabled, Unkey also stores an AES-encrypted copy of the key in the vault. This lets you recover the key later through the API with the decrypt parameter. Use this when your workflow requires showing users their existing key. See Recovering keys for details.

​
Constraints

Last modified on June 24, 2026