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
Obtain an access token
Call the API from an external service
Step 1: Create an External Service
On your Moodle site, click Site Administration > Plugins > Web services > 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
Step 2: Add Functions to the Service
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.
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 > Plugins > Web services > API Documentation.
Step 3: Assign Role to User
- 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.
- 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.
- Navigate to Site Administration > Plugins > Web services > Manage protocols
- Make sure that the REST protocol is enabled
- If it is disabled, click the eye icon next to it to enable it
The external service is now properly configured.
Step 4: Obtain 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.
- Navigate to Site Administration > Plugins > Web services > Manage tokens
- Click the Add link at the bottom of the page
- Select the authorized user you chose in the previous section and choose the appropriate external service from the drop-down menu
- Click the Save changes button
- You will now see your new access token listed
- Copy the token for use in the next section
Step 5: Call 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:
Wrapping it all up
Now you know the basics of how to use the Web Services Application Programming Interface (API) in Moodle.