Bots and Robotic Process Automation (RPA)

Healthcode understands our customers may need to automate their business processes that may involve interaction with systems. We allow bot-based automation subject to certain restrictions.

An end user must authenticate and supervise any bots that access our systems and they must have a Healthcode Account. If a new Healthcode Account needs creating, contact your Healthcode Business Development Manager (BDM) to get started.

The sequence diagram below depicts the overall authentication and authorisation workflow and the following sections describe the different steps. Note, the documentation only provides a high-level overview and expects the implementors to refer to the OAuth 2.0 specification for low-level details.

Registering the RPA client

All client apps that access Healthcode products and services as part of automation workflows must be registered with us first. Please contact your Healthcode BDM with the following info:

Name and a brief description of the client app.

The post-authentication endpoint URL – you must supply the full and exact endpoint address including the domain name as well as the full path.

We’ll issue you with a client id. This client ID value needs to be maintained as a configurable parameter for the client app and will be required during the authentication-authorisation workflow.

Initialising the auth workflow

The first step in the authentication workflow is for the client app to generate a cryptographically-random code verifier and from that a code challenge.

Authentication by the supervisor user

To complete the authentication step, the client app needs to integrate with Healthcode’s Single Sign-on (SSO) server. The SSO server supports the standard OAuth 2.0 Authorization Code grant workflow with Proof Key for Code Exchange (PKCE). The interface conforms with the OAuth 2.0 specification. We don’t currently support the Client-Initiated Backchannel Authentication workflow.

The client app needs to redirect the supervisor user to the SSO server’s authorisation endpoint as detailed below. The endpoint conforms with the OAuth 2.0 /authorize endpoint specification.

Endpoint

The Healthcode auth server publishes the discovery document at https://auth.healthcode.co.uk/.well-known/openid-configuration.

If you’re testing against Healthcode sandbox (UAT) environment, the discovery document is published at https://auth.uat.healthcode.co.uk/.well-known/openid-configuration

The authorisation endpoint must be looked up from the discovery document using key authorization_endpoint.

Request

{authorization_endpoint}?
  response_type=code&
  client_id=example_rpa_app&
  state=xyz123&
  redirect_uri=https%3A%2F%2Frpaapp.example.com%2Fpostauth HTTP/1.1
  --header 'Host: example.com'

Where,

Field	Type	Description
response_type	String	This must always be “code”.
client_id	String	The client id issued by Healthcode as part of the registration process.
redirect_uri	String	The URL of the post-auth page. The SSO server will redirect the user here after the authentication step along with parameters for completing further steps (refer to the next sections).
state	String	This is an opaque value that can be used by the client to maintain state between the request and callback. The SSO server includes this value when redirecting the user-agent back to the post-auth page (as supplied under the redirect_uri parameter). The parameter SHOULD be used for preventing cross-site request forgery as described within the OAuth 2.0 specification.
Host (header)	String	The client app domain.

Response

After completing the authentication step, the SSO server will redirect back to the redirect-uri address provided, supplying a temporary authorisation code.

{redirect_uri}?code=AbC123def456g7hi89JKlm0123&state=xyz123

Where,

Field	Type	Description
code	String	Temporary authorisation code that can be redeemed to obtain access token in the next step.
state	String	Played back value of the `state` parameter supplied during the initial redirection to the authorisation endpoint.

Retrieving the access token using the temp authorisation code and code verifier

Our 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.

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 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=authorization_code&
                    client_id=example_rpa_app&
                    redirect_uri=https%3A%2F%2Frpaapp.example.com%2Fpostauth&
                    code=AbC123def456g7hi89JKlm0123&
                    code_verifier=padghwys171229akdd'

Where,

Field	Type	Description
grant_type	String	This must always be “authorization_code”.
client_id	String	The client id that was issued by Healthcode as part of registration process.
redirect_uri	String	URL of the post-auth page. This must match the value supplied during the earlier redirection to authorisation endpoint.
code	String	The temporary authorisation code that was retrieved in the previous step.
code_verifier	String	Code verifier generated earlier during the initialisation step.

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
}

On successful completion of the above steps, the RPA client can access Healthcode products and services supplying the access token within the Authorization header.