API client settings

  • Updated on Jul 22, 2025
  • Published on Aug 6, 2024
  • 2 minute(s) read
Prev Next

When setting up or editing an API client, you can configure the following client-specific settings.

Setting

Description

Notes

Client rate limit

Set the maximum query complexity cost per minute for this client.

If this value exceeds the value set for the Client rate limit set at the site level, then the site-level limit will be used instead.

Token expiration

This sets the length of time access tokens will be valid before expiring.

The default length of time is 1 day.

Changing this setting only impacts new tokens; any existing tokens will continue to honour the expiry time set at the time of their creation.

Error response

This setting determines how much information will be provided in API responses when errors occur for this client. Select one of the following options:

  • Site default (X): This client will use the option selected for Default error response in the site-wide API settings

  • None: API responses will not return any specific information about the error

  • Normal: API responses will return specific information about why the error occurred

  • Developer: API responses will return specific information about why the error occurred, including a full stack trace

By default, clients will use the Site default (X) option. If the Default error response setting is changed at the site level, all clients using the Site default (X) option will start using the selected option.

API Client IP Whitelisting

Available from Totara 19.1

Site administrators can restrict which IP addresses are allowed to make requests using a specific API client. This provides greater security and control over how external systems interact with your Totara site via the external API.

Why use IP whitelisting?

Previously, any system with access to a valid API client ID and secret could use the external API, regardless of where the request originated. This meant API usage could not be restricted to trusted systems or networks. To address this, a new Allowed IP addresses field has been added to the API client settings. This allows administrators to specify which IP addresses are permitted to send requests using the selected API client. By default, all IP addresses are allowed. However, you can choose to restrict access by specifying allowed IPs in this new field.

Where to find the setting

To use this feature, ensure the external API is enabled and at least one API client has been created. See the following guides for setup instructions:

Once these are in place:

  1. Go to Quick-access menu > Development > API > API Clients > Edit client settings

  2. Locate the new Allowed IP addresses field.

  3. Leave the field empty to allow requests from any IP address (default behaviour).

  4. To restrict access, enter one or more allowed IP addresses, each on a separate line.

When an incoming request is made using this API client:

  • If the request originates from an allowed IP address, the API call will proceed as normal.

  • If the IP address is not in the whitelist, the request will be blocked. The type of error response depends on the “Error response” setting:

    • Normal: Returns a 403 Forbidden response.

    • None: Returns a 404 Not Found response.

    • Developer: Returns developer-level debugging information explaining why the request was blocked.

The new Allowed IP addresses field supports:

  • Full IP address: 192.168.0.1

  • Partial IP address: 192.168 (matches any address starting with this value)

  • IP range: 192.168.0.10-20 (matches all addresses from .10 to .20)

  • CIDR notation: 231.54.211.0/20

Join the Totara Community for more resources to help you get the most out of Totara. 


© Copyright 2026 Totara Learning Solutions. All rights reserved.