Healthcode employs a central auth server to expose both OpenID Connect and OAuth 2.0 interfaces to enable both front-end-based integration as well as server-to-server integration.
The server-to-server API integration primarily involves three steps.
- Obtaining API credentials. This is a one-off activity you need to do in order to configure integrating applications to securely connect to Healthcode APIs.
- Use the API credentials to obtain a secure access token from the Healthcode auth server.
- And finally, the secure access token can be used to call individual APIs.
Obtaining API credentials
In order to integrate with the Healthcode APIs, you will need to obtain API credentials.
If you do not already have a Healthcode Account, contact your Healthcode business development manager to get started.
If you have a Healthcode Account, you can generate new API credentials through the API Keys section. Please note you need to be a manager contact for the given account to be able to access this feature.
You will need both the API Key Id and API Key values for connecting to Healthcode APIs (we will use them in the next section to obtain an access token).
If you are a software service provider, you will need to request the relevant organisation with the Healthcode site subscription to create a new set of API credentials and issue the same to you.
Below are some of the best practcies we recommend in terms of the API keys usage.
Use separate API keys for each app
This practice limits the scope of each key. If one API key is compromised, you can delete or regenerate the impacted key without needing to update your other API keys.
Delete unused API keys
Periodically check the API keys under your account and delete those that are no longer in use.
Please note, deleting an API key may take a few moments to propagate.
Store API keys securely
The API keys obtained from Healthcode must be stored securely.
Also, the keys must only be used within the backend layer to make server-to-server API calls and must never be propagated to the UI layer.
Retrieving access token using API id and key
Healthcode APIs support the standard OAuth 2.0 Client Credentials grant workflow for authentication. The API id and key you obtained above represent the OAuth 2.0 client id and client secret values.
In order to obtain the token, the integrating applications need to call the Token API as detailed below. The endpoint conforms with the OAuth 2.0 /token endpoint specification.
Endpoint
The Healthcode auth server publishes the discovery document at https://auth.healthcode.co.uk/.well-known/openid-configuration.
If you are testing against Healthcode sandbox (UAT) environment, the discovery document is published at
https://auth.uat.healthcode.co.uk/.well-known/openid-configuration
The token API endpoint must be looked up from the discovery document using key token_endpoint.
Request
curl --request POST
--url '{token_endpoint}'
--header 'Content-Type: application/x-www-form-urlencoded'
--header 'Authorization: Basic ZXByYWN0aWNlOkFKTklz...QVZsYmE5Zw=='
--data-urlencode 'grant_type=client_credentials'Where,
| Field | Type | Description |
|---|---|---|
| grant_type | String | This must always be “client_credentials”. |
| Authorization (header) | String | Encoded credentials in the format base64(apikeyid:apikey). |
Response
The Response from the API contains a signed JSON Web Token (JWT), the token’s type (which is Bearer), and info on how much time before the token expires in Unix time (86,400 seconds means 24 hours).
{
'access_token':'eyJraWQiOiJyc2ExIiw...PBmmkLHDI7Ueg',
'token_type':'Bearer',
'expires_in':86400
}Calling APIs with the access token
Once you obtain an access token from the Healthcode auth server, you can call the APIs by supplying the access token along with any API-specific input parameters. The access token must be supplied in the Authorization header.
curl --request GET \
--url '{get_remittance_endpoint}' \
--header 'Authorization: Bearer eyJraWQiOiJyc2ExIiw...PBmmkLHDI7Ueg' \
--header 'content-type: application/json'
--header 'SU-SiteId': 'HC00ABC'