API Keys

An API key is a Control Plane Service (CPS) product credential that authenticates REST calls into the platform (for example POST /transaction/sale/pos). It is not an OIDC token — a Logto-issued JWT is not accepted in its place. For how the key is actually used on the wire, see Before you begin and REST transactions.

The API Keys page (/api-keys) lists every key for your active organization and drives the create, edit, rotate, and revoke flows.

Create

1. Click Create key.
2. Choose the scopes the key may use (see Scopes below) — leave all unchecked for an unscoped key.
3. Optionally set a rate limit (requests/second) and an IP allowlist. Leaving either blank means no limit and no restriction.
4. Submit. Dashboard-created keys are always live-environment keys — there is no environment to choose.

The result view then shows the plaintext secret (sk_live_…) exactly once. Copy it into your own configuration now — CPS stores only a hash of the key, so it can never be shown again. If you lose it, rotate the key to issue a replacement.

Edit

Edit changes a key’s scopes, rate limit, and IP allowlist — its mutable metadata. The environment is fixed at creation and shown read-only; to change it, create a new key. The secret itself is never shown or changed by Edit — use Rotate for that.

Clearing the rate-limit field and saving explicitly removes any existing limit, rather than leaving it unchanged.

Rotate

Rotating a key revokes its current secret in CPS and issues a replacement with the same scopes, rate limit, and IP allowlist. Update your integration with the new plaintext secret shown once the rotation completes — the same one-time display as Create.

The old secret stops authenticating new SMP validation calls immediately, but SMP caches a successful validation for up to 30 seconds (bounded by its MaxValidationCacheTtl setting) to avoid calling CPS on every request. If the old secret was used shortly before you rotate it, it can keep authenticating against that cached result for up to that window rather than being cut off the instant you click Rotate.

Use Rotate when a secret may have leaked or as part of routine credential hygiene, without having to recreate the key’s scopes and limits from scratch.

Revoke

Revoking a key is irreversible: there is no way to reactivate it, and to keep using the same permissions and limits afterward you must create a new key. CPS marks it revoked immediately, but the same bounded SMP validation cache described under Rotate applies here too — a secret used just before revoking it can keep authenticating for up to that cache window (30 seconds by default) rather than being cut off instantly. Make sure no active integration still depends on it before confirming.

Scopes

Scopes grant the least privilege an integration needs — for example keys:read, usage:read, or a wildcard like kms:*. Grant the narrowest set that lets the integration do its job; an unscoped key (no scopes selected) is unrestricted.

Rate limits

The rate limit caps requests per second for that key specifically. Leave it blank for no limit. It is independent of any platform-wide throttling.

Show revoked keys

By default the list shows only active keys. Check Show revoked keys to also list keys that have been revoked — useful for auditing what existed historically, since a revoked key’s row is kept rather than deleted.