# 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

```bash
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

```bash
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

```bash
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.

```bash
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".

```bash
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.