Setting Up
API Keys & Scopes
Create least-privilege keys, understand scopes, and rotate safely.
Creating a key#
From Developers → API keys in the portal (admin) or API keys on the developer dashboard, click Create API key:
- Name — describe the integration, not the person.
- Scopes — tick only what the integration needs.
x:writeimpliesx:read. - 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#
students:write, faculty:write, groups:write, licenses: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
Originheader, 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.