REST API tokens
What are REST API tokens?
REST API tokens let external apps and scripts connect to Moodle's new REST API. There are two ways to get one:
- Personal access tokens: users create their own tokens from their preferences, for example for a script they run themselves.
- OAuth 2 clients: an administrator registers an app, such as a mobile app. Users then sign in from the app and approve the access it asks for.
Personal access tokens and user-approved apps work within the user's existing permissions.
In Moodle 5.3, only a few parts of Moodle are available through the REST API. More will be added in later releases.
What are scopes?
Every token has one or more scopes, which limit what it can do, such as viewing your own user account or viewing course content. Moodle shows each scope's name and description wherever you choose one.
Some scopes come in two versions: one for any user, such as View any user account, and one for yourself, such as View your own user account. The broader version includes the narrower one. Plugins can add their own scopes, so the list can vary between sites.
Developers can find out which scopes each part of the REST API needs in the scopes developer documentation. Administrators can see which scopes each part of the REST API needs in Site administration > Development > Moodle REST API UI (SwaggerUI).
How are they different from web service tokens?
Moodle's Web services have their own tokens, which users find in Security keys and administrators manage in Site administration > Server > Web services > Manage tokens. Those tokens work with the existing web service functions.
REST API tokens work with the REST API only, and are created and managed on their own pages. The Enable web services setting doesn't affect them.
What do sites need?
- Personal access tokens: users need the capability
moodle/api:createtoken. The Authenticated user role has it by default, so every user can create tokens unless an administrator removes it. - OAuth 2 clients: the site's Composer dependencies must be installed. Without them, the OAuth 2 clients page doesn't appear. Managing clients needs
moodle/site:manageoauth2clients, which the Manager role has by default.
See also
Related pages:
- Personal access tokens
- OAuth 2 clients
- Web services
- OAuth 2 services: a separate feature that lets Moodle connect to external services such as Google or Microsoft.
Video demos by Andrew Lyons:
Developer documentation:
