Using the External GraphQL API

The External GraphQL API is recommended when connecting an external system to or from Totara. See Available APIs for a summary of the other APIs we offer and their uses.

At the time of release the External GraphQL API has a limited number of available services (focused on the syncing of user data to/from HR systems). Additional services will be developed for future releases.

Video screencast and demo codebase

Watch this developer-focused screencast showing a practical use of the API:

The code developed during the screencast can be found on our public github here:

https://github.com/totara/apidemo

Authentication

All requests to the external API require authentication. The external API uses OAuth 2.0 via the client credentials grant type to authenticate requests. This involves three steps:

Register a client.
Request a token.
Submit a request with a valid token.

Step 1: Register a client

To register a client, log in to your Totara site as a Site Administrator and navigate to Quick-access menu > Development > API > Clients. Click the Add client button and provide information to describe the purpose of your client. Make a note of the client_id and client_secret for step 2.

Registering a client is explained in more detail in the Totara user documentation.

Note that system-level API clients cannot be accessed by tenant users, even if tenant isolation is disabled. This is to prevent possible privilege escalation.

Step 2: Request a token

To programmatically request a token, call the OAuth 2.0 token endpoint as follows, passing the client_id and client_secret obtained during step 1:

curl -X POST 'https://SITE_URL_HERE/totara/oauth2/token.php' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=CLIENT_ID_HERE&client_secret=CLIENT_SECRET_HERE'

If successful, the response will be a JSON-encoded object similar to this:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "YOUR-API-BEARER-TOKEN"
}

Step 3: Submit a request with a valid token

Copy the value from the "access_token" property in the response into the Authorization: Bearer header of your request. See below for how to structure an API request.

Endpoint location

All requests to the external API are made through a single endpoint:

https://YOUR_SITE_URL/api/graphql.php

If this URL cannot be found, confirm your site is running a compatible Totara version (Version 17.0+). Requests are made via the HTTP POST method with a JSON-encoded body:

 $ curl 'https://YOUR_SITE_URL/api/graphql.php' \
    -X POST \
    -H 'Authorization: Bearer YOUR_API_BEARER_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-binary '{ "query": "query { totara_webapi_status { status } }", "variables": "{}" }'

See the Authentication section above for how to obtain a valid Bearer token.

The expected response for this request would be the following JSON object:

{
  "data": {
    "totara_webapi_status": {
      "status": "ok"
    }
  }
}

See Using GraphQL APIs for more on the structure of requests and responses.

The totara_webapi_status query used in the example above is a good test query to check that your API is available and authentication is working. It will always return 'ok' for the status field.

Access control

The abilities granted to an API client are controlled by the service account that is assigned to it. See the user help documentation for more information about service account configuration.

Access token behaviour

Access tokens are requested for specific clients as described above. It is possible to request multiple separate access tokens for the same client at the same time (requesting a token won't expire existing tokens). The expiry time of a token is set at the time it is requested based on the default_token_expiry admin setting.

If a client is disabled, all tokens associated with that client will temporarily stop working, but will start working again if the client is re-enabled.

Rate limiting and query complexity

See API rate limiting and query complexity for more information about how complexity is calculated and rate limiting is applied.

API documentation

API reference documentation is built into the site itself, since that allows it to provide the most specific reference guide for the particular Totara version being used, including documentation for any customisations. In-product documentation can be found via Quick access menu > Development > API > API documentation.

We also provide a copy of the reference documentation for releases with significant API changes.

For information about changes to the API see the release notes.

Deprecation and versioning

See Changes to the GraphQL APIs for details on API deprecation and versioning.