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:
| Scenario | Response |
|---|---|
| Basic Authorization Header missing, or credentials invalid | HTTP 401 Unauthorized, with a www-authenticate header challenge of "Basic" |
| Valid credentials but with inappropriate permissions | HTTP 403 Forbidden |
| Valid credentials with appropriate permissions | Authentication 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:
| Scenario | Response |
|---|---|
| Bearer Authorization Header missing, or token invalid | HTTP 401 Unauthorized, with a www-authenticate header challenge of "Bearer" |
| Valid token but with inappropriate permissions | HTTP 403 Forbidden |
| Valid token with appropriate permissions | Authentication 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.