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>'
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>'