# Keys, events and webhooks

Keys, short-lived tokens, apps, the event stream, webhook endpoints and the test project.

Scopes for this area: `keys:read`, `keys:write` and `keys:admin`.

25 operations.

## key

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/keys` | List the keys of the project (never their secrets). | read | `rivier keys key list` |
| POST | `/keys` | Mint a key. The secret is returned once. | admin | `rivier keys key create` |
| POST | `/keys/{id}/rotate` | Replace a key with a twin; the old key keeps working for the overlap. | admin | `rivier keys key rotate` |
| DELETE | `/keys/{id}` | Revoke a key at once. | admin | `rivier keys key revoke` |

## token

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/keys/tokens` | Mint a short-lived token from this key: at most its scopes, minutes to live, no key management. | write | `rivier keys token create` |

## event

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/keys/events` | The key audit: created, rotated and revoked, never a secret. | read | `rivier keys event list` |

## events

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/events` | Events from a cursor, limited to the modules the key can read. | read | `rivier keys events list` |
| GET | `/events/catalogue` | Every event type, and the operation that raises it. | read | `rivier keys events catalogue` |
| GET | `/events/stream` | A server-sent stream of events; reconnect with Last-Event-ID to resume. | read | `rivier keys events stream` |

## webhook

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/webhooks/endpoints` | The endpoints that receive signed events. | read | `rivier keys webhook list` |
| POST | `/webhooks/endpoints` | Register an https endpoint. The signing secret is returned once. | admin | `rivier keys webhook create` |
| DELETE | `/webhooks/endpoints/{id}` | Remove an endpoint and its delivery log. | admin | `rivier keys webhook remove` |
| POST | `/webhooks/endpoints/{id}/enable` | Switch an endpoint back on after repeated failures. | admin | `rivier keys webhook enable` |
| POST | `/webhooks/endpoints/{id}/replay` | Send an endpoint the events it takes from a point in the stream on. | admin | `rivier keys webhook replay` |

## delivery

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/webhooks/deliveries` | The delivery log: attempts, answers, and what is waiting to be retried. | read | `rivier keys delivery list` |
| POST | `/webhooks/deliveries/{id}/replay` | Send one delivery again. | admin | `rivier keys delivery replay` |

## sandbox

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/sandbox` | Is this key live or test, and does the project have a test project yet? | read | `rivier keys sandbox get` |
| POST | `/sandbox/seed` | Fill the test project with a small demo brand per module, made through the API's own routes. | admin | `rivier keys sandbox seed` |
| GET | `/sandbox/deliveries` | What the test project would have sent: calls to outside services, recorded and not made. | read | `rivier keys sandbox deliveries` |

## app

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/oauth/apps` | The third-party apps registered for the project. | read | `rivier keys app list` |
| POST | `/oauth/apps` | Register an app: its redirect addresses and the most it may ask for. A confidential client's secret is returned once. | admin | `rivier keys app create` |
| DELETE | `/oauth/apps/{id}` | Switch an app off and end every grant it holds. | admin | `rivier keys app remove` |

## consent

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/oauth/authorize` | What the consent screen shows: the app, the scopes (bounded by the person's role) and where it returns. | read | `rivier keys consent get` |
| POST | `/oauth/authorize` | The person's decision; answers the address to send the browser to. | write | `rivier keys consent decide` |

## grant

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| DELETE | `/oauth/grants` | Take back what you handed out: every app, or one with ?appId. | write | `rivier keys grant revoke` |