Set up API access scopes

When an API's OAuth token is generated, it is assigned a set of scopes that specify its access level. The definition of each scope is contained in a scopes configuration file.

You can add or modify scopes by creating a pull request with changes to this file and a support ticket containing a link to the PR.

API scope descriptions

During the authorisation code flow, the end user sees a message asking them to give the application permission to perform an action based on the scope being requested. The scope description is used for this message, so it should clearly describe the verb-led action the application will perform.

Examples of this short, focused style: 'Submit a customs declaration' or 'Get state pension calculation'. If multiple scopes are requested, they are presented in a bulleted list.

API definitions

An API declares the scope required to call an endpoint as part of its OpenAPI Specification definition. There are three types of API definitions:

A standard application accessing a user-restricted endpoint needs a valid grant generated by an end user going through the OAuth authorisation code grant flow. When an application first sends users to the grant flow, it includes the scopes users must authorise. These are translated into human-readable descriptions shown to the user before authority is granted, ensuring the user gives explicit permission for an application to interact with the platform on their behalf.

Example scopes

create:products
read:products
update:products
delete:products

Granular scopes and privileged applications

Sometimes multiple privileged applications, each with access rights to different datasets, call the same API. If an API-producing team knows datasets are likely to change, or that new consumers may want access to a slightly different dataset, they can add logic to their application configuration. A new consumer can then be securely added by:

  • updating the API's app config to specify the new scope and associated dataset
  • redeploying the API
  • creating the privileged application with the new scopes in the access approval tool

Confidence level

API scopes can be given an optional confidence level. If a confidence level is not assigned to a scope, the platform defaults it to CL50.

Authorisation checks

Services should always perform authorisation checks before handling incoming requests that operate on user-specific data. Each service is responsible for permitting or denying access to callers based on their permissions.

If the ability to call a particular API should be limited to certain users, an authorisation check must be in place.

Need support? If you are blocked at any step, contact your support route for help.

Got feedback? We are always improving this guidance. Share feedback to help improve the documentation.