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 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://keycloak.{environment}.corti.app/realms/{Tenant-Name}/protocol/openid-connect/token

The full request body looks like this:

Client Credentials request body
grant_type: "client_credentials"
scope: "openid"
client_id: "the-provided-client-id"
client_secret: "********"
For the test environment beta-eu, the Tenant-Name is copiloteu.
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 300s/5min. 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

So if you for example 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

Find the specifications for the request body in the API Reference

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

For the test environment beta-eu, the Tenant-Name is copiloteu.

API call request header
Tenant-Name: <tenantname>
Authorization: Bearer <access_token>
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://url returned}&token=Bearer {access_token}