How API keys and scopes work

This page explains the MapleGather API-key model: what a scoped key is, why the full token is shown only once, and what rotation means — for anyone building on the API or managing integrations.

The short version

A MapleGather API key is a bearer token (mg_<env>_<32 base32 characters>) that grants access to specific API resources based on the scopes you assign. The token is shown exactly once when it is created or rotated. Revocation is permanent and immediate. Rotation is the safe way to replace a token in production without downtime.

How it works

Scopes define what a key can do. Each scope follows the resource:action pattern — for example, members:read lets the key call list and get operations on member records; members:write lets it create, update, and delete. A key carries only the scopes you explicitly assign; there is no implicit escalation.

The key token is a cryptographically random string in the format mg_live_<32 base32 characters> (or mg_test_... for keys scoped to a test-mode environment). It is returned by api_keys_create or api_keys_rotate once only — in that single response. After that, only the first eight characters (the prefix) are visible in the admin console. This one-time reveal is intentional: it pushes you to store the token in a secrets manager at creation time rather than relying on MapleGather as a secrets store.

The masked list — api_keys_list shows only the prefix, scopes, status, last-used timestamp, and expiry. The full token is never exposed in a read response.

Why it works this way

The one-time token reveal is a security posture, not an oversight. If a platform stored and re-displayed your secret tokens, a breach of that platform would expose every integration credential. By making the token available only once and never storing it in a retrievable form, the blast radius of a potential breach is contained.

Rotation

Rotation (api_keys_rotate) issues a new token on the same key record and keeps the old token valid for seven days. The seven-day overlap window lets you deploy the new token to your infrastructure before the old one expires — no downtime required.

After rotation, the old token’s expiry (previousKeyExpiresAt) appears in the reveal surface so you know exactly when it stops working.

Revocation

Revocation (api_keys_revoke) is terminal and irreversible. The row stays in the key list for audit purposes (greyed, with the revocation timestamp) but the token is immediately invalidated. Any API call using a revoked token returns 401. You cannot un-revoke; issue a new key if you need to restore access.

Edge cases & boundaries

A key with expiresAt in the past is expired, not revoked. The difference matters: an expired key can indicate that the key’s intended TTL has elapsed; a revoked key indicates explicit administrative action.
You cannot rotate a revoked or expired key. Issue a new key instead.
If you close the browser tab or dismiss the secret-reveal surface before copying the token, the token is unrecoverable. Rotation is the only path to a new token on that key.