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 → Active → (optional: Disable / Expire / Exhaust credits) → Revoke
StateDescription
ActiveKey passes verification and deducts from rate limits and credits
DisabledKey exists but fails verification with DISABLED
ExpiredKey passed its expiration timestamp, fails with EXPIRED
ExhaustedKey’s remaining credits reached zero, fails with USAGE_EXCEEDED
RevokedKey is permanently deleted and can’t be restored

​
Create a key

Keys are created through the API, SDK, or dashboard. Each key requires an apiId to associate it with an API and its keyspace. On creation, you can configure:
OptionDescription
prefixOverride the API’s default prefix for this key
nameHuman-readable label
metaArbitrary JSON metadata returned on every verification
expiresUnix timestamp (ms) when the key expires
remainingNumber of verifications before the key is exhausted
refillAutomatic credit refill schedule (interval and amount)
ratelimitOne or more rate limit configurations
rolesRoles to attach for RBAC
permissionsPermissions to attach directly
externalIdLink the key to an identity in your system
enabledSet to false to create a disabled key
environmentTag the key with an environment label (for example, live or test)
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:
FieldDescription
validWhether all checks passed
codeOutcome code (VALID, NOT_FOUND, RATE_LIMITED, EXPIRED, DISABLED, INSUFFICIENT_PERMISSIONS, USAGE_EXCEEDED, FORBIDDEN)
keyIdThe key’s unique identifier
metaCustom metadata attached to the key
remainingCredits left after this verification (if configured)
ratelimitRate limit state (limit, remaining, reset timestamp)
identityIdentity information if the key is linked via externalId
permissionsPermissions attached to the key
rolesRoles attached to the key
enabledWhether the key is enabled
expiresExpiration timestamp (if set)

​
Features

Each key can carry several optional features:
FeatureWhat it controlsLearn more
Rate limitsRequests per time windowKey rate limits
CreditsTotal request quotaUsage limits
RefillAutomatic credit reset (daily or monthly)Auto-refill
ExpirationTime-based validityTemporary keys
Roles and permissionsRBAC access controlAuthorization
MetadataArbitrary JSON returned on verificationPassed as meta at creation
EnvironmentLabel for separating live and test keysEnvironments

​
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 API 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

LimitValue
Key prefix max length8 characters
Metadata max size64 KB (JSON)
Rate limit configurations per key10
Permissions per key1,000
Roles per key1,000
PageDescription
APIs overviewAPI and keyspace configuration
API key managementQuick start guide with code examples
IdentitiesLink keys to users for shared rate limits
Sentinel authenticationVerify keys at the gateway
API referenceFull endpoint documentation
Last modified on March 30, 2026