Authentication and Authorization

OAuth2

Verto uses the OAuth 2.0 authorization protocol which allows external applications to securely obtain requested access to our API services with the user’s approval. There are multiple types of OAuth2 authentication. We support the password grant, authorization code grant, and PCKE.

Each of authorization protocol follows the same steps

Request User Authorization
Request Access Token
Use Access Token

Password Grant Type

OAuth 2.0 Password grant type involves sending the username, password, in exchange for an access token. This is the simplest way to authenticate with Verto’s API. This method of establishing a connection is recommended for machine to machine integrations.

Step 1: Request Access Token

Make a POST request to https://<project-name>.vertoclinic.com/oauth/token with the following data in the request body.

Request Parameter	Description
`grant_type`	`password`
`username`	Verto Flow email
`password`	Verto Flow password

Password Grant Request Example:

import requests
import json

PROJECT_NAME = "verto-project"
API_ENDPOINT = f'https://{PROJECT_NAME}.vertoclinic.com/oauth/token'

payload = json.dumps({
    "grant_type": "password",
    "username": "example@verto.ca",
    "password": "mypass"
})
headers = {
    'Content-Type': 'application/json'
}

response = requests.request("POST", API_ENDPOINT, headers=headers, data=payload)

print(response.json())

Password Grant Response Example:

{
  "access_token": "YAPNG48WzlZ9_zPMDNrqe2obOcvBtp_r75ar6zJ5MyU",
  "token_type": "Bearer",
  "expires_in": 1800,
  "created_at": 1649209661
}

App Registration for Authorization Code Grant Type (Closed Beta)

For more complex integrations, the first step in accessing Verto’s API is registering your application. You can register an OAuth application through

Admin > OAuth Applications > New

Once you’ve registered your app, a Client ID and Client Secret will be generated. Make sure to keep this safe. The final step is to figure out which OAuth flow is right for your purpose.

OAuth2 URLs

The <project-name> is a placeholder for the specified client Verto is working with.

URL	Description
`https://<project-name>.vertoclinic.com/oauth/authorize`	Base authorization URL
`https://<project-name>.vertoclinic.com/oauth/token`	Token URL

Authorization Code Grant Type (Closed Beta)

The authorization code grant is used by exchanging an authorization code for an access token. Upon authorizing the user, an authorization code will be received via the redirect URL. That authorization code will then be used to request an access token. This method is compatible with a SMART on FHIR app launch as well as the IUA standard as published by Canada Health Infoway.

Step 1: Request User Authorization

Make a GET request to https://<project-name>.vertoclinic.com/oauth/authorize with the following query parameters.

Query Parameter	Description
`response_type`	`code`
`redirect_uri`	URI to handle successful user authorization. This must match Flow’s OAuth app settings that were made during registration
`client_id`	Client Id that was generated when you first registered your app
`scope`	A list of scopes separated by spaces
`code_challenge`(PKCE)	A challenge derived from the code verifier

Authorization URL Example:

https://<your domain>.vertoclinic.com/oauth/authorize?response_type=code&client_id=698748565528628455&scope=appointments.write%20units.read&redirect_uri=https://myapp.com

When requesting authorization from Verto Flow for the first time, they will be prompted by Verto with the following.

Allow Verto Access

Once authorized, the user will be redirected to the redirect_uri and an authorization code will be in the code query parameter.

Redirect URL Example:

https://myapp.com/?code=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU

Step 2: Request Access Token

Copy the code from the redirect URL and set it in your request body when making a POST request to https://<project-name>.vertoclinic.com/oauth/authorize. Please also include the following in your header and request body.

Header	Description
Content-Type	`application/json`

Request Parameter	Description
`client_id`	Client Id that was generated when you first registered your app
`client_secret`	Client Secret that was generated when you first registered your app
`grant_type`	`authorization_code`
`code`	The authorization code that was in redirect URL during the callback
`redirect_uri`	URI to handle successful user authorization. This must match Flow’s OAuth app settings that were made during registration
`code_verifier`(PKCE)	A generated encrypted string that’s used to match `code_challenge` given in the authorization request

Token Request Example

import requests
import json

PROJECT_NAME = "verto-project"
API_ENDPOINT = f'https://{PROJECT_NAME}.vertoclinic.com/oauth/token'

payload = json.dumps({
    "grant_type": "authorization_code",
    "code": "47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU", #authorization code obtained from redirect uri
    "client_id": "698748565528628455",
    "client_secret": "bgvx4c6flst843gssis0",
    "redirect_uri": "https://myapp.com"
})
headers = {
    'Content-Type': 'application/json'
}

response = requests.request("POST", API_ENDPOINT, headers=headers, data=payload)

print(response.json())

Access Token Response Example

{
  "access_token": "YAPNG48WzlZ9_zPMDNrqe2obOcvBtp_r75ar6zJ5MyU",
  "token_type": "Bearer",
  "expires_in": 1800,
  "created_at": 1649209661
}

Using Proof Key for Code Exchange (PKCE)

On top of authorization code grant, Verto also supports Proof Key for Code Exchange (PKCE) for single page applications without the need of a client secret.

Since the response of PCKE is the same as the Authorization Code Grant, the following examples we will only show examples requests parameters. You man notice that everything is the same as the Authorization Code Grant example except we added the optional code_challenge and code_verifier to support PKCE.

PKCE Authorization URL Example:

https://verto.ca/oauth/authorize?response_type=code&client_id=698748565528628455&scope=appointments.write%20units.read&redirect_uri=https://myapp.com&code_challenge=M9euIB9ruBFOzGsuVmH1zDOnaHyFlbuQjdkkjfldqms

PKCE Token Request Example:

import requests
import json

PROJECT_NAME = "verto-project"
API_ENDPOINT = f'https://{PROJECT_NAME}.vertoclinic.com/oauth/token'

payload = json.dumps({
    "grant_type": "authorization_code",
    "code": "47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU", #authorization code obtained from redirect uri
    "client_id": "698748565528628455",
    "client_secret": "bgvx4c6flst843gssis0",
    "scope": "appointments.write units.read",
    "redirect_uri": "https://myapp.com",
    "code_verifier": "j85G8Xqsb9pXZu3QrAxW-FEjL1aD.bRCbJigMGDs8pyBeUTEzRSWo_5cXtnHnIWT0tcbeWeLFBB_H~oqVV" #need to verify the code challenge
})
headers = {
    'Content-Type': 'application/json'
}

response = requests.request("POST", API_ENDPOINT, headers=headers, data=payload)


print(response.json())

Using Access Token

Finally, we can now make requests to Verto’s resource servers, all that is needed is to the add the access_token as the Authorization Bearer header. In following example we will make a GET request to retrieve units from Verto server.

Request Example:

import requests
import json

PROJECT_NAME = "verto-project"
API_ENDPOINT = f'https://{PROJECT_NAME}.vertoclinic.com/api/v1/units'
access_token = "YAPNG48WzlZ9_zPMDNrqe2obOcvBtp_r75ar6zJ5MyU"

payload = {}
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.json())

Response Example:

[
  {
    "id": 19,
    "name": "Test Unit 1",
    "hospital_id": 1,
    "created_at": "2022-01-13T10:30:33.107-05:00",
    "updated_at": "2022-03-22T10:52:52.441-04:00",
    "send_reports": false,
    "fax_number": "",
    "report_start_date": null,
    "report_time": null,
    "report_recurrence": null,
    "report_recurrence_type": null,
    "report_job_id": null,
    "email": "",
    "hospital": {
      "id": 1,
      "name": "Demo Hospital",
      "shortname": "THP",
      "created_at": "2021-03-31T14:59:07.769-04:00",
      "updated_at": "2021-03-31T14:59:07.769-04:00",
      "veritas_id": null
    }
  },
  {
    "id": 24,
    "name": "Test Unit 2",
    "hospital_id": 1,
    "created_at": "2022-03-10T10:46:49.357-05:00",
    "updated_at": "2022-03-10T10:46:49.357-05:00",
    "send_reports": false,
    "fax_number": null,
    "report_start_date": null,
    "report_time": null,
    "report_recurrence": null,
    "report_recurrence_type": null,
    "report_job_id": null,
    "email": null,
    "hospital": {
      "id": 1,
      "name": "Demo Hospital",
      "shortname": "THP",
      "created_at": "2021-03-31T14:59:07.769-04:00",
      "updated_at": "2021-03-31T14:59:07.769-04:00",
      "veritas_id": null
    }
  }
]