Skip to main content
The API keys screen. A new key is shown once, at creation time.

The API keys screen. A new key is shown once, at creation time.

Machine keys begin with gp_live_ and belong to one workspace. They authenticate API routes only through an exact bearer header:

​
Scope catalog

Create the narrowest key that supports the client.

​
One-time delivery

1

Create

An authorized browser session requests the key name, scopes, and optional CIDR list.
2

Receive once

The secret is encrypted for delivery and shown through a session-bound handle. The delivery window is 10 minutes.
3

Store it

Copy the secret into the client’s secret store. During delivery, the server keeps an encrypted session-bound payload and an HMAC-SHA-256 verifier.
4

Acknowledge

Acknowledgement activates the key and clears the encrypted delivery payload. The HMAC verifier remains for authentication.
The same session can resume an unexpired pending delivery. The key cannot be recovered after acknowledgement or expiry.

​
Rotation

Rotation creates a pending replacement with the same scopes and CIDR policy. The old key stays active until the new secret is acknowledged. At acknowledgement:
  • The replacement becomes active.
  • The old key enters a 15-minute grace state.
  • Confirming rotation revokes the old key early.
  • Otherwise authentication lazily revokes it when grace expires.
Revocation is idempotent.

​
CIDR restrictions

Keys can contain strict IPv4 or IPv6 CIDR ranges. The direct peer address is authoritative unless:
  1. GEO_TRUST_PROXY=1, and
  2. the direct proxy peer is loopback.
Only then can the application use the forwarded client address. Forwarding headers from an untrusted peer are ignored. A missing or nonmatching effective address returns HTTP 403.

​
States

​
Session-only management

API key creation, delivery, acknowledgement, rotation, confirmation, and revocation require a browser session. An API key cannot mint or rotate other keys.
A key is a workspace credential, not a user credential. Removing a team member does not automatically revoke keys they may have copied.