This is a new service - your feedback (opens in a new tab) will help us to improve it.

  1. Home
  2. Authorisation

Authorisation


Endpoint types

DfE APIs have 3 types of endpoint:

  • open access
  • application-restricted
  • user-restricted

Each type of endpoint has a different level of authorisation.

Open access endpoints

Open access endpoints are the least restricted type of endpoint and service general data held by DfE.

Open access endpoints:

  • only need a valid API subscription key to be passed (no access token)
  • usually allow self-approval for subscriptions

For more information, see the open access endpoint in the tutorials section.

Application-restricted endpoints

Application-restricted endpoints do not need to be authorised by the end user. These endpoints do not give access to sensitive personal data.

To pass an application-restricted endpoint, you need:

  • a valid API subscription key
  • an access token

Find out how to request an access token for application-restricted endpoints in our tutorial.

We use the open standard OAuth 2.0 with the client credentials grant (opens in a new tab) to generate an access token. If the endpoint requires a scope (opens in a new tab), your application must include this scope when creating the access token.

The access token lasts for one hour. When it expires you must request a new one.

For the authorisation rules, read the specific API endpoint documentation.

User-restricted endpoints

User-restricted endpoints need to be authorised by the end user (for example, academy trusts or school authorities). They generally give access to sensitive personal data.

To pass a user-restricted endpoint, you need:

  • a valid API subscription key
  • an access token

Find out how to request an access token for application-restricted endpoints in our tutorial.

We use the open standard OAuth 2.0 (opens in a new tab) with the client credentials grant (opens in a new tab) to generate an access token. This allows the end users to authorise your application to interact with DfE on their behalf without sharing their access credentials.

The end user authenticates directly with us, using their IDAMS and DfE sign-in accounts, and authorises specific scopes.

We then issue an OAuth 2.0 access token that is specific to the end user. Your application passes the access token in subsequent API requests to user-restricted endpoints.

Following the latest OAuth 2.0 security best current practice (opens in a new tab), DfE APIs do not support implicit and password OAuth grant types.

Credentials

Your credentials are your client ID and your client ‘secret’ - a kind of password. Developer Hub supplies 2 active client secrets (primary and secondary) at any one time.

We use your credentials:

  • to identify and authorise your application during each step of the process
  • when you test your application with sandbox APIs or run against the production APIs

Client ID

Your client ID is a unique identifier that we create when you register your application on the Developer Hub.

Client secret

A client secret is a unique passphrase that you generate to authorise your application. It is known only to your application and the authorising server.

The client secret is the same as a password. You should not store it as plain text. You must encrypt your client secret before you store it so it is less likely to be compromised.

Rotate your client secrets regularly

When you register your application, we assign your application 2 client secrets - primary and secondary. They are usually valid for 2 years.

You can rotate your primary and secondary secrets to shorten the time an access key is active. This will reduce the impact to your business if it is compromised.

To rotate your client secrets:

  • Sign in to the Developer Hub.
  • Check that your secondary secret for the application has a reasonable amount of time before it expires (for example, at least 6 months).
  • Update your application to use the secondary secret.
  • Check that your application is working with the secondary secret.
  • Regenerate your primary secret.