Keys & permissions
A key is a Moodle identity
Every MCP key wraps a Moodle web-service token and the roles that token acts with. When an assistant calls a tool, your Moodle executes it as that user — so Moodle's own permissions are the outer boundary. A key issued for a teacher cannot read another teacher's course, no matter what the assistant asks.
Recognised roles: admin, manager, editingteacher, teacher, student
and user. Tools outside a key's roles are neither listed to the assistant nor
executable.
Key lifecycle
Keys are created in Organization → Moodle → MCP keys or from the plugin's Users section (those show up with created by: moodle). The value is displayed once — store it like a password. From then on the panel only knows its hash, its last four characters and its status.
| State | Effect |
|---|---|
| Active | Works normally. |
| Suspended | Rejected until reactivated. Reversible. |
| Revoked | Permanently dead. Not reversible — mint a new key. |
| Expired | Past its expiry date, if one was set. |
Authentication happens on every request, so a state change takes effect on the assistant's very next call — no session to wait out.
Restricting a key further
Roles set the ceiling; these restrictions lower it. They're useful when you hand a key to a person, a department or an automation that shouldn't have everything their Moodle account can do.
- Read-only — the key can only run tools that read. Every mutating tool is refused, even if the role allows it. The safest thing to hand out.
- Allowed tools — an explicit list of tool names. Anything not listed is refused, which is how you build a narrow, purpose-made key.
- Allowed courses — a list of course ids. Any call naming a course outside the list is rejected, so a key can be scoped to one programme.
- Expiry — an optional date after which the key stops working. Good for contractors, pilots and demos.
Restrictions are enforced on the server for every call, including calls routed through the gateway tools — an assistant cannot talk its way around them.
Which key powers what
- An external assistant uses whichever key you configured in that client.
- The panel's AI chat uses the key an owner or admin selects in Organization → Moodle → AI chat identity. Its roles become the chat's Moodle identity, resolved server-side on every message; the key value never reaches the browser.
- Sign in with your Moodle (OAuth) binds the assistant to the identity of whoever signed in, with no key to copy or store.
Good practice
- One key per person or per integration — shared keys can't be revoked selectively.
- Prefer read-only unless the assistant genuinely needs to change Moodle.
- Set an expiry on anything temporary.
- Review last used in the keys list and revoke what's gone quiet.
- Rotate the key when someone leaves, rather than hoping the mailbox was clean.