# API Keys & Scopes

> Create least-privilege keys, understand scopes, and rotate safely.

Canonical: https://grout.app/developer/documentation/setting-up/api-keys/

## Creating a key

From **Developers → API keys** in the portal (admin) or **API keys** on the developer dashboard, click **Create API key**:

1. **Name** — describe the integration, not the person.
2. **Scopes** — tick only what the integration needs. `x:write` implies `x:read`.
3. **Rate limit** — requests per minute, 10 to 6 000. Default 600.

The plaintext key (`grt_live_` + 32 characters) is shown **once**. The portal then only shows the prefix and the last four characters. Up to 25 active keys per institution.

## Scopes

| Scope | Grants |
|---|---|
| `students:read` / `students:write` | List and read students · provision, update, suspend, map personal emails |
| `faculty:read` / `faculty:write` | List and read faculty · provision, update |
| `groups:read` / `groups:write` | Groups and membership |
| `licenses:read` / `licenses:write` | Licenses and device seats · extend, revoke |
| `sso:write` | Mint launch tokens |
| `exams:read` / `exams:write` | Exams, assignments · create, publish, files, hidden-test key |
| `submissions:read` / `submissions:write` | Submissions, scores, proctoring events · grade, void (write also unlocks recordings) |
| `coupons:read` / `coupons:write` | Coupon batches, redemptions · request batches |
| `merits:read` / `merits:write` | Wallets and ledger · credit merits |
| `guardians:read` / `guardians:write` | Guardian links and reports · invite, remove |
| `alpha:read` / `alpha:write` | Alpha Learning data · enroll, award points |
| `institution:read` / `institution:write` | Profile · integration config |
| `webhooks:read` / `webhooks:write` | Endpoints, deliveries, events · create, rotate, replay |

`GET /v1/scopes` returns the same list with descriptions. A request without the right scope gets `403 insufficient_scope` with `required` and `missing` arrays in the body.

## Recommended scope sets

:::tabs
### Roster sync
`students:write`, `faculty:write`, `groups:write`, `licenses:read`
### LMS launch button
`sso:write`, `students:read`
### Gradebook
`submissions:read`, `exams:read`, `webhooks:write`
### Exam authoring
`exams:write`, `groups:read`, `faculty:read`
### Read-only reporting
`students:read`, `licenses:read`, `submissions:read`, `merits:read`, `alpha:read`
:::

## Rotating a key

There is no in-place rotation; create a new key, switch the integration, then revoke the old one. Revocation is immediate. Usage per key is visible under **Usage** on the keys table (requests, errors and rate-limited calls per day, top routes).

## Storing keys

- Keep keys in a secret manager or environment variable. Never commit them, never ship them to a browser or mobile app.
- The API accepts requests without an `Origin` header, so server-to-server is the intended mode.
- If a key leaks, revoke it in the portal; the audit log records who created and revoked it.

:::danger
A key is as powerful as its scopes across your **entire** institution. Prefer several narrow keys over one broad key.
:::