Sign in

v1

latestOpenAPI 3.0.32026-07-17183583.3 KB
ApiKeys

Import API Key

Imports an external API key into the system. Allows importing keys from legacy systems or external providers. The raw key is hashed (SHA-512/256 over network_id + 0x00 + raw key) and stored; the original key is never retained. Imported keys support token derivation (JWT/Macaroon) like issued keys.

POST /v2alpha1/admin/importedApiKeys
{
  "raw_key": "sk_live_abc123xyz",
  "name": "Imported Stripe Key",
  "actor_id": "user_123"
}
post/v2alpha1/admin/importedApiKeys

Request body

actor_idstring

actor_id is the identifier of the entity that owns this imported key. Required so every imported key is traceable to an actor for revocation and audit queries.

metadataobject

metadata is a free-form JSON object for caller-defined attributes (e.g., source, environment, tags). Values may be strings, numbers, booleans, arrays, objects, or null. Total serialized size is capped at 4KB. AIP-148 metadata field.

namestring
raw_keystring
request_idstring
scopesstring[]
ttlstring

ttl sets the expiry as a duration from now. Encoded as a google.protobuf.Duration (string ending in "s", e.g. "3600s"). Accepted bounds: 1s to 315360000s (~10 years). If unset or zero, the project default TTL applies. For convenience, the server also accepts Go-style duration strings ("24h", "30m", "1h30m") and an extended unit set ("1d", "1w", "1mo", "1y"; approximations: 1mo = 30d, 1y = 365d). Clients should prefer the standard Duration encoding for portability.

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

Response

A successful response.

actor_idstring
create_timestring date-time
expire_timestring date-time
key_idstring
last_used_timestring date-time
metadataobject

metadata is a free-form JSON object for caller-defined attributes (e.g., source, environment, tags). Values may be strings, numbers, booleans, arrays, objects, or null. Total serialized size is capped at 4KB. AIP-148 metadata field.

namestring
revocation_descriptionstring

revocation_description provides free-form context for a revocation. Only set when revocation_reason is PRIVILEGE_WITHDRAWN. JSON API change: field was formerly revocation_reason_text. Field number 13 is unchanged so the change is wire-compatible for binary proto encoding.

revocation_reason'REVOCATION_REASON_UNSPECIFIED' | 'REVOCATION_REASON_KEY_COMPROMISE' | 'REVOCATION_REASON_AFFILIATION_CHANGED' | 'REVOCATION_REASON_SUPERSEDED' | 'REVOCATION_REASON_PRIVILEGE_WITHDRAWN'

RevocationReason provides structured revocation reasons inspired by RFC 5280. Used in both admin and self-revocation flows.

  • REVOCATION_REASON_UNSPECIFIED: Default zero value. Use a specific reason; UNSPECIFIED is rejected by admin and self-revocation endpoints.
  • REVOCATION_REASON_KEY_COMPROMISE: The key was leaked or believed to be in the hands of an unauthorized party.
  • REVOCATION_REASON_AFFILIATION_CHANGED: The owning actor's relationship with the issuer changed (e.g., role change, departure).
  • REVOCATION_REASON_SUPERSEDED: A new key has replaced this one as part of a rotation.
  • REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only. The actor's privilege to use this key was withdrawn by an operator. Self-revocation requests using this reason are rejected with InvalidArgument. Pair with description on the admin revoke requests to record the operator-supplied justification.
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.
update_timestring date-time
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