API troubleshooting
If you are trying to use our APIs and are having difficulty, this page contains some common problems or issues that might help.
Service account issues
Can't see the user you want to select in the Service Account search field
There are a number of limitations on which users can be selected to be a client service account:
- Cannot be deleted or suspended
- Cannot be a guest user
- Cannot be a system administrator
- For tenant clients - the assigned tenant of the user must match the client's tenant
- For system clients - the user must be a system-level user (not assigned to a tenant)
If an existing service account user has become invalid, you can navigate to the Edit client page within Totara to see a validation error with more information about why a client service account is invalid.
You receive the error: 'API user is invalid.' when making an API request
There are a number of limitations on which users can be selected to be a client service account:
- Cannot be deleted or suspended
- Cannot be a guest user
- Cannot be a system administrator
- For tenant clients - the assigned tenant of the user must match the client's tenant
- For system clients - the user must be a system-level user (not assigned to a tenant)
You may receive this error if a valid user was assigned, but then later that user's status changed and they are now invalid. You should either fix the problem with the current service account user or navigate to the Edit client page within Totara to set a new, valid service account user.
Authentication issues
Error 'The request did not contain the required Authorization header. Ensure you set the header in your request and that it is not being stripped by your server or proxy configuration.' in API response
First please ensure that you are setting the Authorization header in your requests. If you are sure you are setting it but are still receiving this message, it is possible the server or a proxy is stripping the header for security reasons. If you are using Apache as your web service this might help:
Permission issues
Receiving permission errors in response
Check that the service account associated with the client that is making the request has been assigned the appropriate permissions. You can see the permissions for a specific user by visiting their profile page, then clicking on Preferences, then either This user's role assignments or Permissions.
The API user role can provide a helpful starting point for granting the correct permissions. For system-level users, assign it in the system context. For tenant-level users, assign it in both the tenant and tenant category contexts. These two locations can be found in separate parts of the admin menu when viewing the tenant's category list:
Receiving null values for specific response fields
Check that the service account associated with the client that is making the request has been assigned the appropriate permissions. You can see the permissions for a specific user by visiting their profile page, then clicking on Preferences, then either This user's role assignments or Permissions.
Note that the default permissions in Totara can restrict access to certain fields that you might expect to see. For example:
- Users' email addresses are not visible to other users unless the maildisplay profile preference is set to Show my email address by default. Otherwise the email address is restricted by various permission checks, such as shared course membership, job relationships and other criteria.
- If the profilesforenrolledusersonly admin setting is enabled then the description field will not be visible to other users until the target user has enrolled in at least one course, or otherwise interacted in such a way as they have a role assignment in the system.
GraphQL client issues
Problems with introspection or inline documentation in GraphQL clients
Review the Max query depth configuration setting for the external API. In some cases, if the value is too low it can prevent the introspection query from completing, preventing external tools from obtaining the schema. A value of at least 15 is recommended.
API documentation
API documentation page displays 'Documentation not found. You must build documentation to view this page.'
If your site is running on an official Totara release then the documentation should already be built and available. However, if you check out a non-release commit (via Git) then the documentation build files will not be there, and you will need to manually build it before you can view the documentation.
See Extending API documentation for more information.
API documentation page displays 'Schema has changed since documentation was last built. Try clearing the site cache and rebuilding documentation to show the current schema.'
We ship official Totara releases with the up-to-date API reference documentation for that specific release, however if you have made any changes to your API schema (due to code customisations) then the system will detect that the site schema no longer matches the schema that the documentation was built for and display this message. You will need to rerun the documentation build process to get the most up-to-date version of the API reference documentation.
See Extending API documentation for more information.
API reference documentation doesn't exactly match documentation provided by other GraphQL clients
The API reference documentation does intentionally mark as undocumented a small number of services that are not relevant for the external API. However, due to schema introspection, these services may still be shown in the auto-generated documentation built by third-party GraphQL clients. This is expected but will not cause any problems.