API & MCP · Scopes
Scopes & permissions
Permissions are checked in three layers, in order. A request must pass all three.
- Scope— the API key must include the scope required by the endpoint (e.g.
certificates:issuefor the batch endpoint). Missing scope →403 MISSING_SCOPE. - Role — some endpoints additionally require
ADMIN(e.g. all external T&C cert operations, notification-template edits). - Per-record ownership— for instructor-scoped actions (a course, a course-completion cert, a submission to review), the resource must be owned by the calling user OR they must be a COAUTHOR / EDITOR collaborator on it. Certificate management(revoke / resend) additionally requires COAUTHOR or admin — EDITORs author lessons but can’t touch issued certs.
Scope reference
| Scope | Grants |
|---|---|
courses:read | List + get courses. Admins see all; instructors see their own + collab. |
courses:write | Create / update / publish courses, modules, and lessons. Instructor keys can only touch their own courses. |
certificates:issue | Issue single or batch external (EMPO T&C) certificates. Admin-only at the role layer — instructor keys with this scope still get 403 on the underlying endpoint. |
certificates:manage | Revoke certificates + resend the recipient email. Scoped to certs the user can manage (their own courses; admin can manage everything). |
templates:write | Override notification email templates (subject / greeting / CTA / footer / enabled). Admin-only. |
Practical examples
- Instructor who just wants Claude to help them author courses:
courses:read, courses:write. - Admin running a cohort training and wants to bulk-issue certs from a CSV via Claude:
certificates:issue, certificates:manage. - Admin automating email-template updates from a design tool:
templates:write.
Mint a key at /dashboard/api-keys and tick only the scopes you need. You can always revoke + remint with a different scope set.