Authorisation

Warning Currently you can only integrate with our sandbox environment. Production integration will be possible when the APIs have reached Beta

Defra uses the OAuth2 Open Standard for access delegation and authorisation to its services and APIs to maintain security and integrity. There are two types of authentication methods in use: user-restricted and application-restricted endpoints, and customers are provided the option of either flow that suits their organisational requirements the most.

All access tokens are time-bound and last for 1 hour at a time and can be silently regenerated by the system in either flow. Access is controlled based on the payload of the token, including the scopes that a user has accepted or the roles that are assigned to a system for a given organisation.

User-restricted

For user-restricted, we use the OAuth2 Code flow which controls access to the services based on a user's credentials, their permissions, and scopes. In this flow, each person from a consuming service is required to have an account registered with us for their organisation. To send an API request and use our services, the user is required to sign-in with their credentials and approve various scopes and permissions, which will generate a unique token for them prior to sending the API requests.

Application-restricted Coming soon

The application-restricted method uses the OAuth Client Credentials with Certificates flow which controls access to services based on system-to-system interaction without a signed in user. In this flow there are no requirements to sign in or register users. The consuming system will have a set of access credentials including a Client Certificate for authentication which it must use to generate a certificate-signed access token prior to sending any API requests. This Certificate is used instead of a secret credential to prove the identity of the remote server.