Skip to main content

Authentication

Most endpoints in the Directory API require authentication.

There are two ways a request can be authenticated, and certain endpoints may require one or other method.

Both methods use HTTP Authentication over HTTPS.

All that differs between them is the Authentication Scheme, and the credentials.

Basic Authentication (Client Credentials)

Some endpoints accept API credentials directly via HTTP Basic Authentication.

The most important of these is the /token endpoint, which can be used to exchange valid credentials for a relatively shortlived access token.

For this, the HTTP Authorization header should be as follows:

Authorization: Basic <credentials>

where <credentials> is a set of client credentials in the form <client-id>:<client-secret> encoded as base64.

Basic authenticated endpoints behave as follows:

ScenarioResponse
Basic Authorization Header missing, or credentials invalidHTTP 401 Unauthorized, with a www-authenticate header challenge of "Basic"
Valid credentials but with inappropriate permissionsHTTP 403 Forbidden
Valid credentials with appropriate permissionsAuthentication successful

Generating Credentials

API Credentials for a given Organisation can be generated by Organisation Administrators in the Directory frontend, as documented in the Directory Guide

Bearer (Token) Authentication

Most public facing endpoints, such as those comprising the Bulk Submissions facility, require an access token.

A client can acquire a token by requesting one from the /token endpoint.

To authenticate a request against a token authenticated endpoint, use HTTP Bearer Authentication.

For this, the HTTP Authorization header should be as follows:

Authorization: Bearer <credentials>

where <credentials> is the JSON Web Token exactly as recieved from the /token endpoint.

Token authenticated endpoints behave as follows:

ScenarioResponse
Bearer Authorization Header missing, or token invalidHTTP 401 Unauthorized, with a www-authenticate header challenge of "Bearer"
Valid token but with inappropriate permissionsHTTP 403 Forbidden
Valid token with appropriate permissionsAuthentication successful

Token Expiry

Access tokens issued by /token are reasonably shortlived; expiring 1 day after they are issued.

Clients should expect to receive HTTP 401 Unauthorized responses when using an expired token. In this event, they should proceed the same way as any other occurrence of an HTTP 401 Unauthorized response: seek to acquire a new token from /token with their client credentials.