v1

latestOpenAPI 3.0.32026-07-17183583.3 KB

ApiKeys

Update Issued API Key

Updates metadata, scopes, or rate limits of an issued key without rotating the secret. Use RotateIssuedApiKey to change the secret.

Follows AIP-134: the request body is the IssuedApiKey resource itself, and the update_mask query parameter names the subset of fields to apply. Omitting update_mask is equivalent to a mask of every populated field in the body. To clear a field to its zero value, list it explicitly in update_mask and leave it unset (or empty) in the body.

PATCH /v2alpha1/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ?update_mask=scopes
{
  "issued_api_key": {
    "key_id": "01HQZX9VYQKJB8XQZQXQZQXQXQ",
    "scopes": ["read"]
  }
}

patch/v2alpha1/admin/issuedApiKeys/{issued_api_key.key_id}

Path parameters

issued_api_key.key_idstring required

Query parameters

update_maskstring

The list of fields to update. See AIP-134.

Request body

actor_idstring

create_timestring date-time

expire_timestring date-time

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

Response

A successful response.