API service accounts

About service accounts

When a client makes requests via the external API, those requests are made on behalf of the user account assigned to the client via the Service Account setting.

• All API client request events will be logged as belonging to the service account user.
• Access control checks will be based on the service account user. This means you can use roles and permissions to control the actions a specific client is allowed to perform via its service account user.
• Multitenancy restrictions will be applied to service account users who belong to a specific tenant.

Service account user restrictions

In order to be able to successfully make API requests, the service account user must be valid and have a minimum level of access. For tenant API clients, the service account user must belong to the same tenant as the API client.

The following checks are made to ensure the service account user meets these requirements:

• Does not have a status of deleted or suspended
• Is not a guest user
• Is not a Site Administrator
• The tenant of the service account user matches the tenant of the API client (e.g. system-level user for system clients, or belongs to the same tenant as the client for tenant-level clients)

If one or more of these checks fails then all requests to the API from the client will fail and the client will be marked as invalid. You will then need to update the service account to select a new valid service account user.

Service account roles and permissions

The access that a specific client will have within the system will be controlled by the roles assigned to the client's service account. When configuring the service account, it is best practice to limit the service account to only grant the permissions it needs. This means that, if the API client tokens were to be intercepted, it would limit what could be done with them.

There is an API user role that you can assign to the service account which will give broad permission to complete tasks for which there are existing services. This can be narrowed down further by creating dedicated roles for specific tasks and assigning these to service accounts in the appropriate context.

For system-level clients, roles can be assigned in the system context. Tenant-specific clients will only have service accounts that belong to that tenant, so will need to be assigned in a lower context - either the tenant context (for capabilities relating to users) or the tenant category context (for capabilities relating to courses or other system objects). The API user role can be assigned in both of these contexts.

Recommended service account configuration

We recommend creating a dedicated service account user for each client you create. This allows you to specify fine-grained access control for the specific client, and ensures it is possible to audit API usage at the client level.

We recommend configuring your service account users as follows:

• Specify a username, first name and last name that will clearly identify the account as being an automated account, and its purpose. For example, you could name the account 'HR sync API user'. This can help prevent the account from being removed by another Site Administrator.
• Set the Authentication method to No Login to prevent manual login.
• Consider setting a profile image that reinforces the automated nature of the account, such as your company logo.
• Typically, you don't want the service account user to receive emails. You can completely disable notifications for the user by going to their profile, then Preferences > Legacy notification preferences. Here you can check the Disable notifications checkbox.
• Responses received from the API will be displayed in the service account user's time zone. Consider the best time zone and set the user's time zone appropriately in their profile.
• Ensure the service account user has the appropriate permissions for the task it will do. See the Service account role and permissions section for more information.