Authorisation code with PKCE

Oauth flow(1).png

Before you can start the flow, you will need to generate the CODE_VERIFIER and the CODE_CHALLENGE. The CODE_VERIFIER is a random string, between 43 and 128 characters in length, which uses the characters A-Z, a-z, 0-9, -, ., _, and ~. The CODE_CHALLENGE is a URL-safe base64-encoded string of the SHA256 hash of the CODE_VERIFIER

The SHA256 hash must be in binary format before encoding. An example is written in Python, of how you can generate these:

code_verifier = ''.join(random.choice(string.ascii_uppercase + string.digits) for _ in range(random.randint(43, 128)))

code_challenge = hashlib.sha256(code_verifier.encode('utf-8')).digest()
code_challenge = base64.urlsafe_b64encode(code_challenge).decode('utf-8').replace('=', '')

code_verifier, code_challenge`

Request authorization code. To do that, you should redirect the user to the /o/authorize page with the following query parameters:
```
AUTH_HOSTNAME/o/authorize/?response_type=code&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=REQUESTED_SCOPES&nonce=NONCE
```
All the parameters are based on the OAuth 2.0 specification. Do not forget to include the CODE_CHALLENGE, as we will need it when generating the token.

At HealthKey, we currently support three scopes: profile, address, and payment. If you are looking to integrate with us for both authentication and payments, please make sure you include both scopes when making this request. Also, if you require us to send you the user’s address, make sure you ask for the address scope as well.
The user will then be redirected to their HealthKey account. If they’re not authenticated, they will be asked to authenticate.
Once the user is authenticated, we will ask for their consent. We ask the user to approve the app request to access their account based on the scopes specified in REQUESTED_SCOPES.
The user is then redirected back to the specified REDIRECT_URI. The scope parameter is a space-separated list of scopes associated with the user. The redirect includes the authorization code, for example:

https://example.com/oauth/redirect?code=1234567890
The authorisation code is valid for only 60 seconds, so the next request should be made in that time interval.
With the authorization code returned from the previous request (denoted as RETURNED_CODE in the following example), you can request an access_token, using a POST request, with any HTTP client. Your request should look something like this:
```
POST AUTH_HOSTNAME/o/token/

Header: Content-Type:application/json

{
"code": RETURNED_CODE,
"grant_type": "authorization_code",
"code_verifier": CODE_VERIFIER,
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"redirect_uri": REDIRECT_URI
}
```
For this request, it is important to consider the type of application you have: public or confidential. You can read more about these types of applications here. The client_secret is optional for this request, depending if you want to expose it or not. If you have a public application, we recommend not sending the client_secret in the request. If your application can be considered private, we recommend sending the client_secret.

Using both the PKCE validation and the client secret is the most secure way of authenticating the request and generating the authorisation token. In the last years, this is the recommendation for all confidential applications.

If you consider configuring your application as a public application, please let us know beforehand. By default, all applications are set up as confidential.
We then use the CODE_VERIFIER to validate the CODE_CHALLENGE we have received previously.
Considering everything went as expected, you can expect your response to look like this:

{
"access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
"token_type": "bearer",
"expires_in": 36000,
"refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
"created_at": 1607635748
}

Refreshing tokens

To retrieve a new access_token, use the refresh_token parameter. Refresh tokens may be used even after the access_token itself expires. This request invalidates the existing access_token and refresh_token.