Authentication
Reading from the API
API consumers are authenticated on a service to service level using:
- Mutual TLS to ensure trust on both the server and client side
- API keys to track and manage usage of the client
Using mutual TLS authentication allows HMPPS to additionally verify the identity of a consumer before securely providing any data and therefore a client must present it’s own TLS certificate, issued by HMPPS, as part of making a request. Providing an API key enables per-client management of API interactions such as rate limiting and therefore a valid API key must also be presented as part of making a request.
Providing a client certificate and key for mTLS is dependent on the tools used to make the request. As an example when using curl the certificate and key are provided as request parameters. If a valid TLS certificate and private key is not supplied the TLS handshake will not complete.
Providing an API key can be done using an HTTP header called x-api-key with the value of the API key as the header value, ensuring it’s not encoded in Base64. If a valid API key is not supplied a 403 Forbidden HTTP response is returned.
Example: Read from an API Endpoint
To make an authenticated data request to the API using the client-specific TLS certificate, private key and API key:
curl --cert <client-cert-file> --key <client-key-file> -X GET https://<environment>.integration-api.hmpps.service.justice.gov.uk/v1/persons/X802678/risks/scores -H 'x-api-key: <api-key>'
On-behalf-of access
External API consumers will identify themselves, as a service, using the common name in their client certificate, but it is also possible to identify the individual that the service is acting on behalf of.
This is done by sending a JWT with the end user details in the optional X-On-Behalf-Of HTTP request header. Contact
the External API support team to agree the configuration for these JWTs, including JWT signature verification.
The exact content of the JWT will be agreed on a case-by-case basis, but would typically include an email address known to the MoJ authorisation systems and user directories.
It is possible for a consumer to allow, but not require, an OBO identity. If OBO user details are supplied then they can be used to expand the base permissions assigned based on the client certificate. If no OBO user details are provided then those base permissions (which may be “none”) will be used.
IMPORTANT - any information provided in response to a request with an OBO user identity can only be shared with that specific individual. Storing this information and/or sharing it with other users may result in revocation of API access.
Interacting with an HMPPS SQS Queue
For consumers that have an SQS queue configured, temporary AWS access credentials that can be used with standard AWS tooling to interact with SQS can be obtained by calling the /token endpoint. Both a valid TLS certificate and an API key must be supplied with the token request. Note that the token endpoint is not versioned.
Example: Create and Read a Temporary SQS Token
To make an authenticated token request to the API using the client-specific TLS certificate, private key and API key:
curl --cert <client-cert-file> --key <client-key-file> -X POST https://<environment>.integration-api.hmpps.service.justice.gov.uk/token -H 'x-api-key: <api-key>'
The token endpoint calls the AWS STS service and returns the Credentials object from the
STS response.
Once retrieved, the token can be used to access the AWS SQS queue directly until it expires.