Keys and rotation
GAUTH has three kinds of long-lived key and one kind of short-lived token.
| prefix | kind | owner | used as |
|---|---|---|---|
gtk_ | client management key | client | Authorization: Bearer gtk_... on the management API |
gsk_ | app secret | app | client_secret in token requests |
gak_ | app user key | app user | Authorization: Bearer gak_... on the public API |
cgt_ | session token | session | Authorization: Bearer cgt_... on the public API |
Every long-lived key is shown in full exactly once, at creation. Afterwards the API returns a hint, which is the first characters of the key.
Labelled keys
A principal may hold any number of labelled keys. Labels are free text up to 60 characters. Use them to tell a laptop from a CI runner.
Client keys
curl -sS "$MANAGE/clients/1/keys" -H "$AUTH"
curl -sS -X POST "$MANAGE/clients/1/keys" -H "$AUTH" \
-H "Content-Type: application/json" -d '{"label":"ci"}'
curl -sS -X DELETE "$MANAGE/clients/1/keys/7" -H "$AUTH"App secrets
curl -sS "$MANAGE/apps/1/keys" -H "$AUTH"
curl -sS -X POST "$MANAGE/apps/1/keys" -H "$AUTH" \
-H "Content-Type: application/json" -d '{"label":"staging"}'
curl -sS -X DELETE "$MANAGE/apps/1/keys/8" -H "$AUTH"App user keys
curl -sS "$MANAGE/apps/1/users/a_9k2m4x/keys" -H "$AUTH"
curl -sS -X POST "$MANAGE/apps/1/users/a_9k2m4x/keys" -H "$AUTH" \
-H "Content-Type: application/json" -d '{"label":"phone"}'
curl -sS -X DELETE "$MANAGE/apps/1/users/a_9k2m4x/keys/9" -H "$AUTH"Self-service keys
A caller can manage their own keys with their own token.
curl -sS "$API/me/keys" -H "Authorization: Bearer $CGT"
curl -sS -X POST "$API/me/keys" -H "Authorization: Bearer $CGT" \
-H "Content-Type: application/json" -d '{"label":"laptop"}'
curl -sS -X DELETE "$API/me/keys/7" -H "Authorization: Bearer $CGT"Rotation
Rotation is a shortcut for "revoke every key of this kind for this owner, then issue one new key".
curl -sS -X POST "$MANAGE/clients/1/rotate-key" -H "$AUTH"
curl -sS -X POST "$MANAGE/apps/1/rotate-secret" -H "$AUTH"
curl -sS -X POST "$MANAGE/apps/1/users/a_9k2m4x/rotate-key" -H "$AUTH"Rotation is immediate. Anything still using an old key stops working.
Revocation
Revoking one key leaves the others alone. Revoking a key is immediate and cannot be undone.
Storage rules
- Store keys in a secret manager or an encrypted store, never in source control.
- Never log a key. The prefix identifies the key type if one appears in a log.
- Use one key per service or device so you can revoke one without breaking the rest.
- Rotate on a schedule and after any suspected exposure.
Key hints
A hint is not a secret. It is the first characters of the key, kept so a human can tell which key is which. Do not treat a hint as a credential.