Clinc Knowledge-Base

# Authentication Endpoint

Clinc supports Token Authentication. There are two supported access token auth methods:

OAuth 2.0 Token Authentication (Bearer) and

Clinc API Key Authentication (App-Key)

# OAuth 2.0 Token Authentication

This is short lived authentication token that expires in 10 hours. They can be generated using the following OAuth 2.0 grant types

# Request Body

# Endpoint: http://instance-url/v1/oauth/

# Headers

Key Value Decription
Content-Type application/x-www-form-urlencoded Only requests with only form-urlencoded content are allowed

# Body

See Grant Type parameter lists below.

# Grant Type Parameters

Client Credentials

This authentication follows "Client Credentials Grant" in oauth2, which is used by registered institutions to authenticate themselves to get read and write access to manage all their users. For example, where the institutions API requests with Clinc are in a secure environment in which the requests and credentials are private.

Parameter Type Required Description
client_id string True Client ID received at registration
client_secret string True Client secret received at registration
grant_type string True Must be set to "client_credentials"
clinc_user_id string True User external ID, can be admin or regular
scope string False Scope determines what access the user gets. Use space to delimit string of desire scopes

Password

This authentication follows "Password Grant" in oauth2, which is used by direct Clinc users. When authenticating, the application tells the users what scopes they have access to which the end users implicitly agree upon.

Parameter Type Required Description
username string True Client ID received at registration
password string True Client secret received at registration
grant_type string True Must be set to "client_credentials"
scope string False Scope determines what access the user gets. Use space to delimit string of desire scopes

Authorization Code

This authentication follows “Authorization Code” in OAuth 2.0, which is used when an application/client exchanges an authorization code for an access token. That way, the user only needs to authorize once. Clinc will serve as the authorization server for this method. More information on Authorization Code Grant can be found in the official documentation (opens new window). See documentation by 3rd party Authorization Code client on usage. The following is information you will need.

Information Description
client_id Client ID provided by Clinc
client_secret Client Secret provided by Clinc
Authorization url /v1/oauth/authorize
Authentication url /v1/oauth

# Sample Request

Javascript (xhr library)

Code Snippet 
const url = 'https://HOSTNAME/v1/oauth/';

// Data when using the client credentials grant type
const data = `
    “client_id=imaclientid”,
    ”&client_secret=imasecret”,
    “&clinc_user_id=1000001”,
    ”&grant_type=client_credentials”
`;
// Data when using the password grant type
const data = `
    “institution=instname”,
    ”&username=demouser”,
    “&password=demopassword”,
    ”&grant_type=password”
`;

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function() {
    if (this.readyState === 4) {
        console.log(this.responseText);
    }
});

xhr.open('POST', url);

xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');

xhr.send(data);

Python (requests library)

Code Snippet 
import requests

url = "https://HOSTNAME/v1/oauth/"

# Data when using the client credentials grant type
payload =(
    “client_id=imaclientid”,
    ”&client_secret=imasecret”,
    “&clinc_user_id=1000001”,
    ”&grant_type=client_credentials”
)
# Data when using the password grant type
payload =(
    “institution=instname”,
    ”&username=demouser”,
    “&password=demopassword”,
    ”&grant_type=password”
)

headers = {
    “Content-Type”: “application/x-www-form-urlencoded",
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Curl (password grant type)

Code Snippet 
curl -X POST \
  https://HOSTNAME/v1/oauth/ \
  -d 'username=demouser&password=demopassword&grant_type=password&institution=instname

# Response Body

Response description:

Key Value Description
access_token string 30 character UUID4 String.
expires_in integer Seconds before this access token is invalidated.
token_type string Will always be “Bearer”. This denotes the token that should before the access token in authorization headers.
scope string Space delimited list of scopes associated with the access token
refresh_token string 30 character UUID4 String. Not currently usable. Used to request a new access token by the client rather than user.

# Sample Response

Response Snippet 
{
    "access_token": "fJUF45JjjqdHjj1EgTDY6vWWo2T1GF",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "ai_model_read account_read account_write query",
    "refresh_token": "MWTcuN2JqMEvGC3IWkH9alIAS9AIDR"
}

# Clinc API Key Authentication

To generate an App-Key, you need to already have an access token generated from a oauth endpoint using either client credentials or password grant type. API Key endpoint supports POST, GET and DELETE for managing your keys.

# POST Request Body

POST supports creating and updating API keys.

# Create API Key

# Endpoint: http://instance-url/v1/apps/applicationtoken/

# Headers

Key Value Description
Authorization Bearer UUID or App-Key UUID The possible token authorization methods include using an OAuth 2.0 Bearer token or Clinc Application API Key.
Content-Type application/x-www-form-urlencoded Only requests with only form-urlencoded content are allowed

# Body

Parameter Type Optional Description
name string False A preferred name that is descriptive of the token's use
scopes string True Space delimited list of scopes that should be associated with the requested Clinc Application API Key. Must be both a subset of the scopes of the requesting user and the institutions allowed application token scopes
referrer_addresses string True A comma delimited list of domains where key is approved for use

# POST Create Response Body

Response description:

Key Value Description
action string Denoted what action was performed, such as Create or Update
id string 36 character UUID4 String.
key string 40 character String.
name string Name given to key
scopes string Space delimited list of scopes associated with this API key
referrer_addresses string Comma delimited list of whitelisted domains
created_at string Creation timestamp

# Sample Request

Javascript (xhr library)

Code Snippet 
const url = 'https://HOSTNAME/v1/apps/applicationtoken/';
const bearerToken = 'TOKEN';

var data = JSON.stringify({
    name: 'Example Token',
    scopes: 'app_read app_write query',
    referrer_addresses: 'example.com, test.com'
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener('readystatechange', function() {
    if (this.readyState === 4) {
        console.log(this.responseText);
    }
});

xhr.open('POST', url);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Authorization', 'Bearer ' + bearerToken);

xhr.send(data);

Python (requests library)

Code Snippet 
import requests
import json

url = "https://HOSTNAME/v1/apps/applicationtoken/"
bearer_token = "TOKEN"

payload = json.dumps({
  "name": "Example Token",
  "scopes": "app_read app_write query",
  "referrer_addresses": "example.com, test.com"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer ' + bearer_token
}

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

print(response.text)

Curl

Code Snippet 
curl --location --request POST 'https://HOSTNAME/v1/apps/applicationtoken/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data-raw '{
    "name": "Example Token",
    "scopes": "app_read app_write query",
    "referrer_addresses": "example.com, test.com"
}'

# Sample Response

Response Snippet 
{
    "action": "Create",
    "id": "5b933269-0ba8-4ca2-b971-786b881d8ba1",
    "key": "f02ec5fb79fb0ff89bd5398ec37722c70c74638c",
    "name": "Clinc Test 2/24/2022",
    "scopes": "app_read app_write query",
    "referrer_addresses": "clinc.com, example.com, 192.168.1.111",
    "created_at": "2022-02-24T17:15:17.217Z"
}


# Update API Key

# Endpoint: http://instance-url/v1/apps/applicationtoken/{token_id}

# Headers

Key Value Description
Authorization Bearer UUID or App-Key UUID The possible token authorization methods include using an OAuth 2.0 Bearer token or Clinc Application API Key.
Content-Type application/x-www-form-urlencoded Only requests with only form-urlencoded content are allowed

# Body

Parameter Type Optional Description
name string True A preferred name that is descriptive of the token's use
scopes string True Space delimited list of scopes that should be associated with the requested Clinc Application API Key. Must be both a subset of the scopes of the requesting user and the institutions allowed application token scopes
referrer_addresses string True A comma delimited list of domains where key is approved for use

# POST Update Response Body

Response description:

Key Value Description
action string Denoted what action was performed, such as Create or Update
id string 36 character UUID4 String.

# Sample Request

Javascript (xhr library)

Code Snippet 
const apiKeyID = 'ID';
const url = 'https://HOSTNAME/v1/apps/applicationtoken/' + apiKeyID;
const bearerToken = 'TOKEN';

var data = JSON.stringify({
    referrer_addresses: 'new_example.com'
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener('readystatechange', function() {
    if (this.readyState === 4) {
        console.log(this.responseText);
    }
});

xhr.open('POST', url);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Authorization', 'Bearer ' + bearerToken);

xhr.send(data);

Python (requests library)

Code Snippet 
import requests
import json


api_key_id = "ID"
url = "https://HOSTNAME/v1/apps/applicationtoken/" + api_key_id
bearer_token = "TOKEN"

payload = json.dumps({
  "referrer_addresses": "new_example.com"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer ' + bearer_token
}

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

print(response.text)

Curl

Code Snippet 
curl --location --request POST 'https://HOSTNAME/v1/apps/applicationtoken/API_KEY_ID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data-raw '{
    "referrer_addresses": "new_example.com"
}'

# Sample Response

Response Snippet 
{
    "action": "Update",
    "id": "32accb39-902b-4946-a733-0417b6034c8b"
}


# GET Request

# Endpoint: http://instance-url/v1/apps/applicationtoken/

# Headers

Key Value Description
Authorization Bearer UUID or App-Key UUID The possible token authorization methods include using an OAuth 2.0 Bearer token or Clinc Application API Key.
Content-Type application/x-www-form-urlencoded Only requests with only form-urlencoded content are allowed

# GET Response Body

Response description:

Key Value Description
tokens list List of tokens

Token Attributes

Key Value Description
id string 36 character UUID4 String.
name string Name given to key
scopes string Space delimited list of scopes associated with this API key
referrer_addresses string Comma delimited list of whitelisted domains
created_at string Creation timestamp

# Sample Request

Javascript (xhr library)

Code Snippet 
const url = 'https://HOSTNAME/v1/apps/applicationtoken/';
const bearerToken = 'TOKEN';

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener('readystatechange', function() {
    if (this.readyState === 4) {
        console.log(this.responseText);
    }
});

xhr.open('GET', url);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);

xhr.send();

Python (requests library)

Code Snippet 
import requests
import json

url = "https://HOSTNAME/v1/apps/applicationtoken/"
bearer_token = "TOKEN"

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

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

print(response.text)

Curl

Code Snippet 
curl --location --request GET 'https://HOSTNAME/v1/apps/applicationtoken/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN'

# Sample Response

Response Snippet 
{
    "tokens": [
        {
            "id": "2fcaf841-d3a8-4573-af9a-b4b8229a1005",
            "name": "Test One",
            "scopes": "app_read app_write query",
            "referrer_addresses": "clinc.com",
            "created_at": "2022-02-23T21:39:38.055Z"
        },
        {
            "id": "32accb39-902b-4946-a733-0417b6034c8b",
            "name": "Test Two",
            "scopes": "app_read app_write query",
            "referrer_addresses": "example.com, 192.168.1.234",
            "created_at": "2022-02-23T20:28:49.601Z"
        }
    ]
}


# DELETE Request

# Endpoint: http://instance-url/v1/apps/applicationtoken/{token_id}

# Headers

Key Value Description
Authorization Bearer UUID or App-Key UUID The possible token authorization methods include using an OAuth 2.0 Bearer token or Clinc Application API Key.
Content-Type application/x-www-form-urlencoded Only requests with only form-urlencoded content are allowed

# DELETE Response Body

Response description:

Key Value Description
deleted string Id of deleted token

# Sample Request

Javascript (xhr library)

Code Snippet 
const apiKeyID = 'ID';
const url = 'https://HOSTNAME/v1/apps/applicationtoken/' + apiKeyID;
const bearerToken = 'TOKEN';

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener('readystatechange', function() {
    if (this.readyState === 4) {
        console.log(this.responseText);
    }
});

xhr.open('DELETE', url);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Authorization', 'Bearer ' + bearerToken);

xhr.send();

Python (requests library)

Code Snippet 
import requests
import json

api_key_id = "ID"
url = "https://HOSTNAME/v1/apps/applicationtoken/" + api_key_id
bearer_token = "TOKEN"

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

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

print(response.text)

Curl

Code Snippet 
curl --location --request DELETE 'https://HOSTNAME/v1/apps/applicationtoken/API_KEY_ID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN'

# Sample Response

Response Snippet 
{
    "deleted": "2fcaf841-d3a8-4573-af9a-b4b8229a1005"
}


Last updated: 02/24/2022

← Query Endpoint →