Agency

Platform APIs do not support browser Javascript initiated calls that required specific CORS (Cross-origin resource sharing) domains to be allow listed, we recommend a BFF pattern in place of direct client interaction with platform APIs

The agency APIs focus on enabling specific actions to be requested or performed by a user with the agent role, via an application (client) able to request the agency_api scope. A brief explanation of the available APIs are provided below along with an OpenAPI 3 API specification document for review here.

Initiate a request to gain agency over user data

In order for an agent (be that a clinician or other health care professional) to be able to query health data belonging to others, they need to issue a consent request to the individual. The individual will receive an email or SMS message indicating that access to health data has been requested. The individual will then be invited to review the request by either logging into an existing account within the Lenus Health platform or by registering (on-boarding).

Once signed in or registered the individual will be presented with the request including:

• The agent or organisation requesting consent
• The specific data being requested

They will then have the option to accept, reject or decide later.

Accepting an agency request

As a security measure the browserRedirectPath and clientNotifyPath values must be an absolute path value starting with /. The platform will use a well known URI configured within the client when generating an absolute URI for callback or redirection.

Upon accepting an agency request consent is established between the individual, the organisation or agent and the originating application. The user will be redirected back to your service and your service will receive a callback request, both are described below.

User Redirect

• The user (patient) will be redirected within their browser to a URI composed of the browserRedirectPath, the following querystring parameters will be included:
  • browserRedirectState value will be returned in a state querystring parameter.

For example if the client URI is configured as https://app.example.com, browserRedirectPath is set to /acceptedAgency and browserRedirectState is set to aaabbb123 then upon accepting the agency the user will be redirected to: https://app.example.com/acceptedAgency?state=aaabbb123

Service Callback

• An asynchronous background server initiated GET request will be made to the clientNotifyPath, the following querystring parameters will be included:
  • The Lenus user id of the user accepting the consent request will be provided in a subject querystring parameter.
  • clientNotifyState value will be returned in a state querystring parameter.

For example if the client URI is configured as https://app.example.com, clientNotifyPath is set to /notifyAcceptAgency and clientNotifyState is set to aaabbb123 then upon accepting an anonymous GET request will be made to: https://app.example.com/notifyAcceptAgency?subject=00000000-0000-0000-0000-000000000000&state=aaabbb123 (where subject is the lenus Id of the user).

Rejecting an agency request

If the individual rejects the request then no further communications or callbacks are made. The request is deleted and agency will not be established.

Deciding later

If the individual chooses to decide later they will be able to return to the request via the email or SMS message and proceed with either accepting or rejecting.

Generate an agency query token

Once agency is established, in order to query data, you need to firstly request a one time query token that encodes verification of the individuals (subjects) for which your data query is associated. A query token is cryptographically generated from a list of known sub identifiers for users over which your authenticated user has consent. The token will expire after 30 seconds, after that period another token will need to be requested.

Review the /querytoken endpoint for request and response definitions.

Retrieve claims for consented users

It is possible to query a list of claims related to the individuals for which consent is in place. The /claims endpoint will present a series of arrays containing claims for each individual.

Client credentials grant type flow

Client credentials grant type has been implemented to allow calls to the agency API specifically for background services or services that do not use an interactive login associated with a user (clinician).

There is a sample project available to demonstrate its use: Client Credentials sample

---