Sign in

v1

latestOpenAPI 3.0.32026-07-17183583.3 KB
ApiKeys

Verify API Key

Verifies a single API key or derived token. Validates the credential's signature, expiration, and revocation status. Works with any credential type (issued keys, imported keys, JWT, macaroon). The response includes the resolved key_id, actor_id, scopes, and metadata. Admin access only.

Cache Control (HTTP Headers):

  • Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup
  • Cache-Control: no-store - Bypasses cache read AND write (never cached)
  • Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)
POST /v2alpha1/admin/apiKeys:verify
{
  "credential": "sk_live_abc123..."
}
post/v2alpha1/admin/apiKeys:verify

Headers

Cache-Controlstring

Cache-directive controlling the verifier cache. no-cache forces a fresh database lookup (cache read is bypassed). no-store additionally prevents the result from being written to the cache. Any other value is ignored.

Pragmastring

HTTP/1.0 alias for Cache-Control: no-cache. Behaves identically when set to no-cache; ignored otherwise.

Request body

credentialstring

Response

A successful response.

actor_idstring
error_code'VERIFICATION_ERROR_UNSPECIFIED' | 'VERIFICATION_ERROR_INVALID_FORMAT' | 'VERIFICATION_ERROR_EXPIRED' | 'VERIFICATION_ERROR_REVOKED' | 'VERIFICATION_ERROR_NOT_FOUND' | 'VERIFICATION_ERROR_SIGNATURE_INVALID' | 'VERIFICATION_ERROR_INTERNAL' | 'VERIFICATION_ERROR_IP_NOT_ALLOWED' | 'VERIFICATION_ERROR_RATE_LIMITED'
  • VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)
  • VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid
  • VERIFICATION_ERROR_EXPIRED: Credential has expired
  • VERIFICATION_ERROR_REVOKED: Credential has been revoked
  • VERIFICATION_ERROR_NOT_FOUND: Credential not found in database
  • VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed
  • VERIFICATION_ERROR_INTERNAL: Internal server error during verification
  • VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges
  • VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)
error_messagestring
expire_timestring date-time
is_validboolean

is_valid reports whether verification succeeded. It is true only when the credential parses, the signature checks out, the key was found, all policy gates (expiry, revocation, IP allowlist, rate limit) pass, and the key's status is KEY_STATUS_ACTIVE. When false, error_code and error_message describe the reason. Use this field for authentication decisions; use status to inspect lifecycle state independently.

issuerstring

The configured token issuer for this project. For derived tokens (JWT/macaroon), this matches the iss claim embedded in the verified token.

key_idstring
metadataobject

metadata mirrors the metadata stored on the verified key. AIP-148 metadata field.

rate_limit_remainingstring int64

Approximate number of requests available before the rate limit is reached (commercial-only, only set when enforcement is active).

rate_limit_reset_timestring date-time

Time when the rate limiter returns to full capacity (all quota recovered).

scopesstring[]
status'KEY_STATUS_UNSPECIFIED' | 'KEY_STATUS_ACTIVE' | 'KEY_STATUS_REVOKED' | 'KEY_STATUS_EXPIRED'

KeyStatus represents the lifecycle state of an API key.

  • KEY_STATUS_UNSPECIFIED: Default zero value. Never returned by the server. Treated as ACTIVE for backward compatibility but should not be relied on.
  • KEY_STATUS_ACTIVE: The key is valid and can be used to authenticate.
  • KEY_STATUS_REVOKED: The key was revoked. Verification fails with VERIFICATION_ERROR_REVOKED. See revocation_reason for the cause.
  • KEY_STATUS_EXPIRED: The key passed its expire_time. Verification fails with VERIFICATION_ERROR_EXPIRED. The transition is computed at read time and not persisted.
visibility'KEY_VISIBILITY_UNSPECIFIED' | 'KEY_VISIBILITY_SECRET' | 'KEY_VISIBILITY_PUBLIC'

KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys. Public keys use a different configurable prefix for visual distinction. Both types share the same scope/permission system — visibility is about exposure safety.

  • KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET