verify-key

Verify an API key’s validity and permissions for request authentication. Use this command on every incoming request to your protected resources. It checks key validity, permissions, rate limits, and usage quotas in a single call. Important: Returns HTTP 200 for all verification outcomes — check the valid field in response data to determine if the key is authorized. A 429 may be returned if the workspace exceeds its API rate limit. Required permissions: Your root key needs one of:

api.*.verify_key (verify keys in any API)
api.<api_id>.verify_key (verify keys in specific API)

Note: If your root key has no verify permissions at all, you will receive a 403 Forbidden error. If your root key has verify permissions for a different API than the key you’re verifying, you will receive a 200 response with code: NOT_FOUND to avoid leaking key existence.

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api keys verify-key [flags]

Flags

string

required

The API key to verify, exactly as provided by your user. Include any prefix — even small changes will cause verification to fail.

string[]

Metadata tags for analytics in key=value format. Attaches metadata for analytics and monitoring without affecting verification outcomes. Enables segmentation of API usage in dashboards by endpoint, client version, region, or custom dimensions. Avoid including sensitive data in tags as they may appear in logs and analytics reports.

string

Permission query to check, supports AND/OR operators and parentheses for grouping. Examples: "documents.read", "documents.read AND documents.write", "(documents.read OR documents.write) AND users.view". Verification fails if the key lacks the required permissions through direct assignment or role inheritance.

JSON string

JSON object for credit consumption configuration. Controls credit deduction for usage-based billing and quota enforcement. Omitting this field uses the default cost of 1 credit per verification.

Show credits fields

integer

required

Sets how many credits to deduct for this verification request. Use 0 for read-only operations or free tier access, higher values for premium features. Credits are deducted after all security checks pass. Min: 0, max: 1000000000.

JSON string

JSON array of rate limit checks to enforce during verification. Omitting this field skips rate limit checks entirely, relying only on configured key rate limits. Multiple rate limits can be checked simultaneously, each with different costs and temporary overrides.

Show ratelimits array item fields

string

required

References an existing rate limit by its name. Key rate limits take precedence over identifier-based limits.

integer

default:1

Optionally override how expensive this operation is and how many tokens are deducted from the current limit.

integer

Optionally override the maximum number of requests allowed within the specified interval.

integer

Optionally override the duration of the rate limit window in milliseconds.

string

Migration provider ID for on-demand key migration from your previous system. Reach out for migration support at support@unkey.com.

Global Flags

Flag	Type	Description
`--root-key`	string	Override root key (`$UNKEY_ROOT_KEY`)
`--api-url`	string	Override API base URL (default: `https://api.unkey.com`)
`--config`	string	Path to config file (default: `~/.unkey/config.toml`)
`--output`	string	Output format. Use `json` for raw JSON
`--body`	string	Send this JSON string as the request body. You cannot combine it with request-building flags.

Examples

unkey api keys verify-key --key=sk_1234abcdef

unkey api keys verify-key --key=sk_1234abcdef --permissions='documents.read AND users.view'

unkey api keys verify-key --key=sk_1234abcdef --tags=endpoint=/users/profile,method=GET

unkey api keys verify-key --key=sk_1234abcdef --credits='{"cost":5}'

unkey api keys verify-key --key=sk_1234abcdef --ratelimits='[{"name":"requests","limit":100,"duration":60000}]'

unkey api keys verify-key --key=sk_1234abcdef --output=json

VALID=$(unkey api keys verify-key --key=$API_KEY --output=json | jq -r '.data.valid')
if [ "$VALID" = "true" ]; then echo "Key is valid"; fi

Output

Default output shows the request ID, followed by the verification result:

req_2c9a0jf23l4k567

{
  "valid": true,
  "code": "VALID",
  "keyId": "key_1234abcd",
  "name": "user-dashboard-key",
  "enabled": true,
  "permissions": ["documents.read", "documents.write", "users.view"],
  "roles": ["editor"],
  "credits": 950,
  "expires": 1735689600000
}

With --output=json, the full response envelope is returned:

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": {
    "valid": true,
    "code": "VALID",
    "keyId": "key_1234abcd",
    "name": "user-dashboard-key",
    "enabled": true,
    "permissions": ["documents.read", "documents.write", "users.view"],
    "roles": ["editor"],
    "credits": 950,
    "expires": 1735689600000,
    "meta": {
      "userId": "user_12345",
      "plan": "premium"
    }
  }
}

When verification fails, the valid field is false and code indicates the reason:

{
  "meta": {
    "requestId": "req_def456ghi789"
  },
  "data": {
    "valid": false,
    "code": "EXPIRED",
    "keyId": "key_5678efgh",
    "name": "temporary-access-key",
    "enabled": true,
    "expires": 1704067200000
  }
}

Possible code values: VALID, NOT_FOUND, FORBIDDEN, INSUFFICIENT_PERMISSIONS, USAGE_EXCEEDED, RATE_LIMITED, DISABLED, EXPIRED.

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Usage

Flags

Global Flags

Examples

Output

​Usage

​Flags

​Global Flags

​Examples

​Output

Usage

Flags

Global Flags

Examples

Output