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:

https://stackoverflow.com/questions/17018586/apache-2-4-php-fpm-and-authorization-headers/33254772#33254772

https://serverfault.com/questions/1094686/rewriterule-e-http-authorizationhttpauthorization-what-does-it-mean

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:

Open

Upgrading a Totara site

When upgrading a Totara site, the API User system role and its associated capabilities remain as they were at the time of the original installation. For security reasons, the upgrade process does not automatically update the API User role with any new capabilities introduced in the latest version.

To utilise new API features that rely on these new capabilities, you must manually assign them to the API User role. You can assign the new capabilities by following these steps:

1. Navigate to Quick-access menu > Permissions > Define roles.

2. Locate the API User role.

3. Select Edit.

4. At the bottom of the page, add the new capabilities.

5. Save.

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.

Key-generation issues

You receive the error: 'Cannot create a new private key'

The 'Cannot create a new private key' error means openssl_pkey_new() fails. When openssl_pkey_new() fails on an Apache web server, it generally indicates an issue with the OpenSSL configuration or the environment in which PHP is running.

Here are several steps you should check to diagnose and fix the problem:

1. OpenSSL and PHP installation:

   • Verify that the PHP OpenSSL extension is enabled. You can check {your site}/admin/environment.php and look for the OpenSSL section.

2. Permissions:

   • Ensure that the Apache user (usually www-data or apache) has the necessary permissions to access the OpenSSL libraries and any directories/files involved in the key-generation process. Totara requires access to a data directory in which to store user data, cache files, temporary files, etc. This directory must be readable and writable by the web server user.

   • Make sure you configure the Apache web server following the recommendations in the Installing Totara documentation.

3. Configuration files:

   • Check the php.ini configuration file to ensure that the OpenSSL extension is not disabled. Look for a line like extension=openssl and ensure that it is not commented out.

   • Verify that there are no errors or issues in the OpenSSL configuration file (openssl.cnf). The location of this file can vary, but it is commonly found in /etc/ssl/openssl.cnf or a similar path.

   • If you are using Microsoft OS you might check the additional DLL you need https://www.php.net/manual/en/openssl.installation.php

4. Memory limits:

   • Ensure that PHP has sufficient memory allocated. Low memory limits in the php.ini configuration file can cause key generation to fail.

5. Error reporting:

   • Review the Apache error logs for any relevant error messages. These logs are usually located in /var/log/apache2/error.log or a similar path.

   • You can enable debugging via /admin/settings.php?section=debugging and attempt to receive the token again - there should be more information available.

6. Dependencies:

   • Ensure that all dependencies required by the OpenSSL and PHP OpenSSL extensions are installed and up to date.