Moodle's Web Services Application Programming Interface (API) allows external systems to perform operations that are normally only accessible from within a Moodle site. This guide will show you how to create an external service in Moodle, how to generate a token for the service, and how to call the service with a POST request from outside the Moodle system. We will create an external service that can be used to assign users to roles in various contexts throughout the Moodle site.
Before You Begin
Create an external service
Add functions to the service: Assign role to user
Assign role to user
Obtain an access token
Create a token
Call the API from an external service
Creating an External Service
On your Moodle site, click Site Administration, then Plugins, then Web services and then External services
Click the Add link at the bottom of the page beneath the Custom services heading
Type a name for your service that describes what it can do in basic terms. Check the Enabled and Authorized users only boxes and click the Add service button
Adding Functions to the Service “Assign Role to User”
Search for the function(s) you wish to use with this external service by name in the search box, and then click the name of the function to add it to the service.
a. Note: You may add as many functions as you like to the service, but it is best to include only functions that are necessary to your use of this service. For a complete list of available functions, visit the Web Services API documentation page on your Moodle site by clicking Site Administration, then Plugins, then Web services, and then API Documentation.
Assign Role to User
1. Return to the External services page and you should see the service you just created listed under the Custom services heading. Click the Authorized users link.
a. Note: Now you must connect this service with a user in the system. The user will run the function(s) on behalf of the external service, and the user's name will appear in the Moodle system logs for the action. For this reason, you may want to create a new user for the purpose of running Web Service functions so it is clear which user is responsible for which actions on the site logs. The user you choose to create must have the correct permissions to perform the action in the system, so it may make sense to assign your Web Services user to a high-level system role such as Manager or Site Administrator.
2. Select the authorized user and click Add. If the user is missing any permissions to perform the service's functions, those permissions will be listed at the bottom of this page.
3. Navigate to Site Administration, then Plugins, then Web services, and then Manage protocols
4. Make sure that the REST protocol is enabled
a. If it is disabled, click the eye icon next to it to enable it
5. The external service is now properly configured
Obtaining an Access Token
Before you can use the external service, you must create an access token. This token forms part of your external API call and functions as a password that proves your call has the right to manipulate data on your Moodle site.
1. Navigate to Site Administration, then Plugins, then Web services, and then Manage tokens
2. Click the Add link at the bottom of the page
3. Select the authorized user you chose in the previous section and choose the appropriate external service from the drop-down menu
4. Click the Save changes button
5. You will now see your new access token listed
6. Copy the token for use in the next section
Calling the API from an External Service
To access the external service you created earlier, you need to send a POST request to the appropriate uniform resource locator (URL) for your Moodle site. The URL format is:
The necessary parameters are:
|wstoken||The token you copied from earlier|
|wsfunction||The name of the function you want to perform, e.g. "core_role_assign_roles"|
|moodlewsrestformat||The format you want the results in. Options are "json" or "xml"|
Wrapping it all up
Now you know the basics of how to use the Web Services Application Programming Interface (API) in Moodle.
*Add important callouts here