To use the API you will need to provide two forms of authentication:
A self-signed certificate that you must have previously sent to us and that we have agreed to trust. In order for us to trust your certificate it must meet the following standards:
The private key and public certificate can be generated using the
openssl command-line tool. e.g.
openssl genrsa -out private.key 4096 openssl req -new -x509 -sha256 -key private.key -subj "/CN=YOUR_CLIENT" -days 730 -out public.crt
Note: You must keep your private key safe. It should be deployed as a secret with your client and should not be shared with anyone. (Only the public certificate should be sent to us.)
Should your private key be compromised you must let us know, generate a new one, and send us the, new, public certificate as soon as possible.
An OAuth2 token supplied in an HTTP header as follows:
Authorization: Bearer YOUR_TOKEN
YOUR_TOKEN must be obtained, via OpenID Connect, from our authentication server, https://sso.digital.homeoffice.gov.uk/auth/realms/lev/.well-known/openid-configuration . The exact authentication 'flow' you use will depend on what you have agreed with us.
The Resource Owner Password Credentials grant flow is one of the simpler flows and so it serves as a useful example of obtaining a token. (Though for full details one should read up on OpenID Connect.) Provided you have both cURL and jq available it is possible to obtain a token as follows:
curl -fsS \ -d "client_id=$YOUR_CLIENT_ID&client_secret=$YOUR_CLIENT_SECRET&username=$SOME_USER&password=$SOME_USERS_PASSWORD&grant_type=password" \ 'https://sso.digital.homeoffice.gov.uk/auth/realms/lev/protocol/openid-connect/token' | jq -r '.access_token'
Once you have an access token, you can make requests to the API as follows:
curl -i \ --cert './PATH/TO/YOUR-CLIENT.crt' \ --key './PATH/TO/YOUR-CLIENT.key' \ -H "Authorization: Bearer $YOUR_TOKEN" \ 'https://api.lev.homeoffice.gov.uk/api/v0/events/birth?forenames=John&lastname=Smith&dateofbirth=2010-01-01'
For full details on the endpoints available see the specification.
If you wish to test your client against the mock API then you might also want to send the following headers:
X-Auth-Aud: The name of your client.
X-Auth-Username: The user your client is currently serving.
Both of these can simply be set to dummy values to ease testing. The client certificate and bearer token are not required.