MyPatientPortal OAuth API

About OAuth API

The MyPatientPortal OAuth API utilizes the OAuth 2.0 standard, enables a secure, token-based access to patient health data for third-party applications. It allows developers to request specific permissions from users, ensuring seamless integration with external apps while protecting sensitive information, without requiring login credentials.

This documentation assumes a basic familiarity with the OAuth 2.0 framework and protocol. If you are new to OAuth, you may want to have a look at the basic concepts of OAuth or the actual OAuth 2.0 specification (RFC6749).

About OIDC

We also support OIDC (OpenID Connect) authentication protocol that extends our OAuth 2.0 authorization protocol. When you provide addtional openid scope to your OAuth 2 requests, you will indicate a will to authenticate using OIDC flow.

The configuration for OIDC is available on .well-known/openid-configuration endpoint. Most of OIDC libraries can use it to automatically perform authentication and OAuth 2 authorization for you. With that, you won’t need to manually code anything relating retrieving and refreshing access tokens. It is our recommended way to use this API.

Using OIDC, we also expose userinfo_endpoint that contains detailed information about authenticated user.

Credentials

Client credentials, which include an ID and secret, uniquely identify your application and are used to authenticate it with your patient portal (Authorization Server). They ensure secure API access. Before being able to use the API, reach out to our administrator to generate credentials with the callback URI of your application.

Roles

OAuth 2.0 specifies 4 distinct roles. In the context of your patient portal, these are mapped as following:

• The Resource Owner is your patient portal user on whose behalf appointments are booked.

• Your external application or service acts as the Client and can access Resource Owner's data, but only with their prior permission.

• The OAuth API serves as an interface to the Resource Servers which control access to protected resources by means of tokens.

• Furthermore, the API interfaces to the Authorization Server which after successful authorization issues the appropriate access tokens of Resource Owner.

The interaction sequence between these roles is the following:

1. The Client requests the authorization of Resource Owner. The latter may grant the authorization by logging in to his/her account.

2. The Client receives the user’s authorization from Authorization Server.

3. The Client presents its client ID, client secret and the granted authorization to Resource Server (via the API).

4. Upon validation, Resource Server returns to the client an access token.

5. The Client requests access to the protected resources and signs these requests with the access token.

6. Resource Server, upon successful validation of the access token, returns the requested resource.

Scopes

OAuth scopes limit what actions a Client can perform, such as reading or modifying certain resources on behalf of the Resource Owner. In your patient portal, three scopes are defined in terms of OAuth:

• profile_read: Allows to retrieve Resource Owner’s profile

• appointment_read: Grants access to read appointments and to video consultation

• appointment_write: Allows to book, cancel and reschedule appointments

The following table demonstrates what scope each OAuth endpoint requires

Obtaining authorization

The endpoint /oauth/authorize of your patient portal is used to obtain authorization from the Resource Owner. This authorization is represented in the form of an authorization code which can be subsequently used to request an Access Token. Depending on the use cases, you need to specify the corresponding scopes in request.

A sample of authorization request:

The Resource Owners will be then asked to authenticate themselves to the Authorization Server, verify the requested scopes and grant the permissions.

Upon a successful authorization, the Authorization server directs the Resource Owner back to the callback URI together with a authorization code.

If authorization is turned down, the response will contain error messages.

For more error responses, please check the official specification our API follows.

Requesting access token

After obtaining an authorization code, the Client makes an access token request to the Authorization Server. This request should include the authorization code, client ID, client secret, redirect URI and specific grant type authorization_code.

Upon validation, the server responds with an access token, which the application can then use to access protected resources on behalf of the Resource Owner.

An example of access token in a successful response:

For any malformed or otherwise incorrect request, the included error descriptions are following the OAuth 2.0 Specification.

Refreshing access token

A refresh token request allows Client to obtain a new access token after the original has expired without requiring the Resource Owner to reauthorize. When the access token is nearing expiration, Client sends a request to the Authorization Server, including the refresh token, client ID, and client secret. Grant type must be refresh_token

If valid, the server responds with a new access token, with the same format as described in section Requesting access token, enabling continued access to protected resources.

Retrieving Resource Owner’s profile

Once your application obtains the proper access token, it can request profile information of the Resource Owner with the following cURL command,

A sample of response data:

A walkthrough of appointment booking

This is meant to be used as a quick-start guide only, to help you quickly create first appointment using the API. As Client accesses the resources on behalf of Resource Owner, all requests must be signed by the access token obtained previously.

To understand the full capabilities of the APIs and get more conceived and production-ready examples, please check the Swagger documentation of your patient portal under path /api-docs.

Appointment booking

Step 1: Getting the available insurance

First, retrieve the available insurances for your patient portal:

After fetching a list of insurances, you need to prompt your user about which insurance they would like to use. In this example, we’ll use insurance ID(136) for future usage.

Step 2: Getting the appointment category

To get the appointment categories specified on the Institution, by making use of the selected insurance’s ID (136), make the following request as in the cURL example below, as:

The response contains a list categories with their IDs and names. Make note of an ID of one of those appointment categories(e.g., 53).

Step 3: Getting the appointment type

Now, to get the appointment types specified on the Institution, make the following cURL request using the previous category id 53, plus the insurance id 136 we’ve fetched in the previous steps,

The response provides a set of appointment types. Make a note of the ID of one of them. Example: 198

Step 4: Getting availabilities

To get availabilities (the times you could book an appointment for), we will now need to use the values we’ve found on the earlier steps, being:

• appointment category: 53

• appointment type: 198

• insurance id: 136

The request will be:

Pick a time and note its id from response for request in the next step. Example: 7r8Uq4AD9Rjk9XNN0FSC6UFR5kkqNICCTjpPCbX1uOUJKPfcuRijxYTW_kVCJ0LOWE9pnCfm4thH8sS4XHdPf8OUWWikWmXWLn3e2nngB6ZzQF5q4xp2i6L+8Y75FXW8r3FktJ_qldsXUvgm6cPXl7q1DFjlAm3k8ANNqGBHDQZb+YTSZAMh6xeY--FFj0c3l1F_pUuY9N--ITaASrPXMda95yi_TjAYsw==

Step 5: Booking the appointment using the selected availability

We will now use the /booking endpoint on a POST request to make the appointment.

We add a few parameters to the body of the request, besides the availability ID fetched in previous Step 4 . Here’s an example using curl to make the request:

And on the response, you’ll get the Appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo)

Rescheduling an appointment

Step 1: Getting availabilities (user booking only)

Given the appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo), you can request new availabilities under the same appointment type and category.

The response contains a list of availabilities and their times, in the same pattern as they are in the previous section.

Step 2: Rescheduling appointment

With the availability ID for a selected time, you are able to reschedule the appointment.

Availability ID example:

7r8Uq4AD9Rjk9XNN0FSC6UFR5kkqNICCTjpPCbX1uOUJKPfcuRijxYTW_kVCJ0LOWE9pnCfm4thH8sS4XHdPf8OUWWikWmXWLn3e2nngB6ZzQF5q4xp2i6L+8Y75FXW8r3FktJ_qldsXUvgm6cPXl7q1DFjlAm3k8ANNqGBHDQZb+YTSZAMh6xeY--FFj0c3l1F_pUuY9N--ITaASrPXMda95yi_TjAYsw==

A successful rescheduling moves only the appointment time. It won’t change the original appointment ID.

Cancelling an appointment

By using the previously created appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo)

The success response contains ID of the cancelled appointment.

Using ASAP list

ASAP list is an appointment feature that patients can opt into. They are then notified via email when earlier availability becomes available for their booked appointments.

Configuring appointment type

A prerequisite for a subscribable ASAP list is that institution enable the feature in appointment type configuration by ticking the checkbox 'Allow patients to register for earlier appointment notifications'. In the payload of appointment types request (as shown in step 3 in the previous section), the parameter asap_notifications_enabled indicates the state of the feature.

Booking appointment with ASAP list subscription

An appointment can be booked with ASAP list subscription by using parameter asap_list_opt_in . Considering the aforementioned booking example, the request body will be extended as in the following cURL request example:

As before, it responds with the new appointment ID in the response payload.

ASAP list un-/subscription after booking

It’s also possible to enter or leave the ASAP list after appointments have been booked. As an ASAP list is always appointment-specific, the appointment ID is always required in requests.

Subscription

Email must be provided in the request payload: An example of the curl request with an appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo):

The appointment ID will be in the response payload for a successful subscription.

Unsubscription

Taking the same appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo) for the CURL request,

The shape of the response will be the same as that for subscription.

Getting earlier availability

With an ASAP list subscription, you can request an earlier appointment availability.
By using the appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo), the cURL can be built as follows:

The response contains the appointment detail and an earlier availability, which is in the same format as previously discussed.

Rescheduling appointment to an earlier availability

It works the same way as described in the previous section.