Authentication to the API on all environments is governed by OAuth 2.0. This authentication protocol offers enhanced security measures, ensuring that access to patient data and medical documentation is securely managed and compliant with healthcare regulations.

By default, you will receive a client-id and client-secret to authenticate via grant type: client credentials. This can be modified and extended upon request to authenticate individual users of your application, including options to utilize SSO or SAML.
1

Request an access token

To acquire an access token, make a request to the authURL provided to you:

auth URL
https://auth.{environment}.corti.app/realms/{tenant-name}/protocol/openid-connect/token
For API trial authentication, please replace the above placehoders as follows:
{environment} with beta-eu
{tenant-name} with copiloteu

The full request body that needs to be of Content-Type: "application/x-www-form-urlencoded" looks like this:

Client Credentials request body
grant_type: "client_credentials"
scope: "openid"
client_id: "<the-provided-client-id>"
client_secret: "********"
2

Your access token

It will return you an access_token:

Access token
{"access_token":"ey...","expires_in":300,"refresh_expires_in":0,"token_type":"Bearer","id_token":"e...","not-before-policy":0,"scope":"openid email profile"}

As you can see, the access token expires after 300 seconds (5 minutes). By default as per oAuth standards, no refresh token is used in this flow. There are many available modules to manage monitoring expiry and acquiring a new access token. However, a refresh token can be enabled if needed.

3

Make an API request

Subsequently you use the access_token to authenticate any API request. The baseURL is dependent on the environment:

baseURL API
api.{environment}.corti.app/v2
For API trial use, please replace the {environment} placeholder with beta-eu

If, for example, you are on the beta-eu environment and want to create an interaction as the starting point for any other workflow operations your URL will look like this:

URL to create an interaction
POST https://api.beta-eu.corti.app/v2/interactions/

In your Request Header you also need to include the Tenant-Name parameter:

API call request header
Tenant-Name: <tenantname>
Authorization: Bearer <access_token>
For API trial use, please use {tenant-name} of copiloteu

To authenticate when opening a websocket, the access_token needs to be passed in as URL parameter in addition to the Tenant-Name already part of the url returned upon creating an interaction:

wss url with access_token appended
wss://{stream-url}&token=Bearer {access_token}
Find the full specification for create interaction request in the API Reference