Code grant

Authorization Code Grant

If your client needs to obtain authorization from an existing PKB user in order to interact with the PKB APIs on behalf of that user, then you need to use the Authorization Code Grant workflow.

An example of that scenario would be a mobile app for patients, which allows a patient to grant access to their existing PKB account.

Note: these examples are written for http://sandbox.patientsknowbest.com ; replace the URL as needed if you are connecting to a different environment.

Client loads PKB's authorization endpoint in a browser

Description

The client should generate a URL as follows, and then send the user to that URL in a browser.

GET https://sandbox.patientsknowbest.com/apiAuthorize.action

Parameters

Parameter

Type

Optionality

Description

Example

response_type

Query parameter

Required

Must be "code"

code

client_id

Query parameter

Required

The REST API Client ID  previously issued to you

myClientId

scope

Query parameter

Optional

Allowed values are:

  • PATIENT

  • CLINICIAN

  • TEAMCOORD

If a value is not provided, we will permit a user from any scope that has has been enabled for your REST API Client ID.

PATIENT

state

Query parameter

Optional

Although this is optional, it is  strongly recommended . This should be an opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery, as described in  Section 10.12 .

ANTI_CSRF_12345

redirect_uri

Query parameter

Conditional

If you have several redirect URIs registered against your Client ID, then you must specify this parameter. Otherwise, it is optional.

If you do specify this parameter, you can add additional parameters to the URI on top of the base URI that is associated with your Client ID.

Note that we do support localhost addresses and custom URL schemes for mobile apps.

You are not able to specify a new URI with this parameter.

https://client.example.com/cb

Example

An example of a complete URL is shown below.

https://sandbox.patientsknowbest.com/apiAuthorize.action?response_type= code&client_id=myClientId&redirect_uri=https://client.example.com/cb&scope=PATIENT&state=ANTI_CSRF_12345

Error handling

If there's a problem with the request, PKB will show an error page in the browser.

PKB authenticates the user, and asks if they wish to grant access

Description

In response to the request made in the previous step, PKB will show an authorization page. This will state which client is asking for access (the owner and product name), and prompt the user to enter their credentials if they wish to grant access to the client.

The user will either do this and click "Approve", or they can click "Deny".

If the user clicks "Approve" and the authentication is successful, PKB will generate an Authorization Code. This will be passed back to the client as a URL parameter whilst redirecting the user to the specified redirect_uri. If a redirect_uri was not specified then the single redirect URI already known to be associated with the Client ID will be used.

Note: the authorization code is bound to the Client ID and the redirection URI; the client will need to use the same redirection URI for the next step as well.

Parameters

Parameter

Type

Optionality

Description

Example

code

Query parameter

Required

The authorization code that can subsequently be used to obtain an access token

SplxlOBeZQQYbYS6WxSbIA

state

Query parameter

Optional

The same value that was sent in the request, if present

ANTI_CSRF_12345

Example

An example redirect is shown below. Note that the authorization code is provided as the "code" parameter, and the "state" parameter provided by the client in the intial request is also appended to the URL.

https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=ANTI_CSRF_12345

Error handling

If user clicks "Deny" (or if the authentication fails, or there is another error), then the redirect will include an "error" parameter instead of the "code" parameter.

See section 4.1.2.1 for more information on error codes.

Example Error

An example redirect is shown below.

https://client.example.com/cb?error=access_denied&state=ANTI_CSRF_12345

Client exchanges authorization code for an access token

Request

Description

Once you have an authorization code, you can swap this for an access token and usually a refresh token. The only exception is if the remaining expiry time of the access token exceeds the expiry time remaining of the session (this is rare).

POST https://sandbox.patientsknowbest.com/apiToken.action

Parameters

Parameter

Type

Optionality

Description

Example

grant_type

Form parameter

Required

Must be "authorization_code"

authorization_code

client_id

Form parameter

Required

The REST API Client ID  previously issued to you

myClientId

code

Form parameter

Required

The authorization code returned in the previous step

SplxlOBeZQQYbYS6WxSbIA

redirect_uri

Form parameter

Conditional

If you specified one in the original request, this must match exactly. Otherwise, this is optional.

https://client.example.com/cb

Content-Type

HTTP header

Required

Must be "application/x-www-form-urlencoded"

application/x-www-form-urlencoded

Example

An example of a complete URL is shown below (parameters are shown in the URL for convenience, but implementations should send them in the body of the POST).

https://sandbox.patientsknowbest.com/apiToken.action?grant_type=authorization_code&client_id=myClientId&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https://client.example.com/cb

Response

Description

PKB responds with the access token in JSON, and usually a refresh token. The only exception is if the remaining expiry time of the access token exceeds the expiry time remaining of the session (this is rare).

Parameters

Parameter

Type

Optionality

Description

Example

access_token

JSON parameter

Required

This is the access token that can subsequently be used to authenticate against the relevant API, and gain access to the functionality

2YotnFZFEjr1zCsicMWpAA

token_type

JSON parameter

Required

This is always "Bearer"

Bearer

expires_in

JSON parameter

Required

This indicates the number of seconds for which the access_token is valid

600

refresh_token

JSON parameter

Optional

If the session has not expired, a refresh_token will also be issued. This can be used to obtain a new access_token when the token validity period has expired.

tGzv3JOkF0XG5Qx2TlKWIA

scope

JSON parameter

Optional

This will match the scope specified in step 1

PATIENT

Example

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"Bearer", "expires_in":600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "scope":"patient" }

Error handling

The authorization code is only valid for 10 minutes. If that duration expires, or if another occurrs, then an error response is returned.

See section 5.2 for a full list of error response codes.

Example Error

HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "error":"invalid_request" }

Client exchanges refresh token for new access token

Request

Description

An access token is only valid for a short duration (normally 10 minutes). After that, a new access token can be requested using a refresh token. This will be possible until the session expires (unless your Client ID is configured to have non-expiring sessions).

Refresh tokens can only be used once. If one is submitted that has previously been used, all active tokens for that session will be revoked.

POST https://sandbox.patientsknowbest.com/apiToken.action

Parameters

Parameter

Type

Optionality

Description

Example

grant_type

Form parameter

Required

Must be "refresh_token"

refresh_token

client_id

Form parameter

Required

The REST API Client ID  previously issued to you

myClientId

refresh_token

Form parameter

Required

The refresh token issued at the same time as the most recently valid access token

tGzv3JOkF0XG5Qx2TlKWIA

scope

Form parameter

Optional

The scope of the session

PATIENT

Example

An example of a complete URL is shown below (parameters are shown in the URL for convenience, but implementations should send them in the body of the POST).

https://sandbox.patientsknowbest.com/apiToken.action?grant_type=refresh_token&client_id=myClientId&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&scope=PATIENT

Response

Description

PKB responds with a new access token in JSON and usually a refresh token. The only exception is if the remaining expiry time of the access token exceeds the expiry time remaining of the session (this is rare).

Example

Same as for the initial token request above.

Error handling

Same as for the initial token request above.

 

© Patients Know Best, Ltd. Registered in England and Wales Number: 6517382. VAT Number: GB 944 9739 67.

This API specification and design is licensed under a Creative Commons Attribution 4.0 International License.