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

  1. Home
  2. Reference guide

Reference guide


Follow this reference guide to make sure your application integrates with DfE.

To avoid your application failing without warning when DfE makes changes, read best practice.

Browser support for OAuth 2.0

The OAuth 2.0 authorisation journey is designed to work with most modern browsers as per the list specified on Designing for different browsers and devices. The exception being Internet Explorer 11 which we are looking to release soon.

Coding in the open

The DfE Developer Hub, the underlying API Platform and some of the APIs are coded in the open, as per the GOV.UK Digital Service Standard (opens in a new tab).

The source code is available at https://github.com/DFE-Digital (opens in a new tab). For more details, contact us.

Redirect URLs

Redirect URLs send the user back to your application after successful (or unsuccessful) authorisation, before your application accesses user-restricted endpoints.

You must specify:

  • one or more redirect URLs when you register your application
  • one redirect URL when you send your user to our authorisation endpoint

To protect your application from phishing attacks, your redirect URL for authorisation (in your call to /oauth/authorize) must be the same as:

  • one you used when you created your application
  • the one for exchanging your authorisation code for an access token (in your call to /oauth/token)

Creating your URLs

When registering your application, you can:

  • use the full redirect URL - for example https://www.example.com/auth-redirect
  • use a partial URL - for example https://www.example.com
  • include a port number - for example https://www.example.com:8080/auth-redirect
  • include a query component - for example https://www.example.com:8080/auth-redirect?some_parameter=some_value

When calling our authorisation endpoint, your redirect URL must include a percent-encode - for example https%3A%2F%2Fwww.example.com%2Fauth-redirect

Your redirect URL must not:

  • use http (except for installed applications) - for example http://www.example.com:8080/auth-redirect
  • use an IP address instead of a DNS name - for example https://203.0.113.11/auth-redirect
  • include a fragment component - for example https://www.example.com:8080/auth-redirect#some_fragment
  • be a relative URL - for example /auth-redirect

TLS standards

DfE APIs are only accessible over Transport Layer Security (TLS) 1.2 or higher.