OAuth2: Session Bearer Tokens

In order to access the protected resource, you must first request an access token via the OAuth handshake. The API supports the client_credentials OAuth grant type. It is worth noting that the client_credentials grant type can be used for API calls when there is no existing user, however we suggest registering within the Layar instance before making any calls.

The entire API is secured by OAuth with the exception of the token endpoint /oauth/token, which is secured by basic authentication (learn how to generate tokens here).

Generating API Keys

In order to generate an OAuth access token, you will need an API client ID and secret (aka your authentication keys). These are going to be different than the account username and password credentials that you use in the Layar user interface.

There are several ways you can generate these keys: manually via the Layar user interfaces or via the REST API. All three methods are detailed in How to Get API Keys.

Basic Token Authentication

Once you've generated a client ID and secret, you can use them to configure your session and generate a Bearer token for authentication. You can generate a token for your session via the RESTful endpoint using either the password grant type or client credentials grant type, or by using the Python SDK. All methods are described below.

To start, you must have a client_id and client_secret. There are several ways you can generate these credentials: manually via the Layar user interface, via the REST API, or via the Python SDK. All three methods have been detailed in How to Get API Keys.

🚧

Tokens Expire After 12 Hours

Tokens automatically expire after twelve hours. Pro Tip: You should only ask for a new token if the access_token has expired. Calling the endpoint to get a new access_token every time you call an API works, but we wouldn’t call it the best practice.

Client Credentials Grant Type

You can generate a session token using our /connect/oauth/token endpoint. Use your Vyasa instance URL (i.e. my-instance) as the baseURL and your API keys for the CLIENT_ID and CLIENT_SECRET.

curl -X POST -u CLIENT_ID:CLIENT_SECRET https://my-instance.vyasa.com/connect/oauth/token?grant_type=client_credentials -H "Accept: application/json"

const https = require('https')

var username = 'CLIENT_ID'
var passw = 'CLIENT_SECRET'

var options = {
   host: 'my-instance.vyasa.com', // swap out 'my-instance' with your Layar instance's name
   port: 443,
   path: '/connect/oauth/token?grant_type=client_credentials',
   method: 'POST',
   // authentication headers
   headers: {
      'Authorization': 'Basic ' + new Buffer(username + ':' + passw).toString('base64')
   }   
};

// make the auth call
request = https.request(options, function(res){
  console.log(`theStatusCode: ${res.statusCode}`)

  res.on('data', d => {
    process.stdout.write(d)
	console.log(`theData: ${d}`)
  })
})

request.on('error', error => {
  console.log(`got an error: ${error}`)

  console.error(error)
})

request.end()

## import dependencies
import requests
import json

## Provide Your Client Instance
baseUrl = 'https://my-instance.vyasa.com' # Your Layar Instance

## Make RESTful call
response = requests.post(f"{baseUrl}/connect/oauth/token?grant_type=client_credentials", 
    headers = {
        'accept':'application/json',
        'content-Type':'application/json'
    },
    auth = ('CLIENT_ID','CLIENT_SECRET') # Your API Keys
)

response.json()

The expected response should look something like this:

{'access_token': '123ab456-c789-0123-af1d-36ca2697122a',
 'token_type': 'bearer',
 'expires_in': 41954,
 'scope': 'read write'}

Tokens via Python SDK

You can use the recipe here, or read along to walk through each line of the configuration.

Walkthrough
Use your Vyasa instance URL (i.e. my-instance.vyasa.com) as the baseURL and your API keys for the clientID and clientSecret.

##Gather relevant URLS
envUrl = 'https://sandbox.certara.ai'
authUrl = f"{envUrl}/connect/oauth/token"
##ClientID and SecretKey (replace with your own keys)
clientId = 'clientId'
clientSecret = 'clientSecret'
##instantiate token variable
token = requests.post(
        authUrl,
        data={"grant_type" : "client_credentials"},
        auth=(clientId, clientSecret),
        headers = {'Content-Type' : 'application/x-www-form-urlencoded'},
        ).json()["access_token"]

This call will generate an active bearer token, which can be used for the next 12 hours for authentication, rather than using your client ID and secret. You can print the active token for your reference using:

# View your session's Bearer token
print(token.text)

Refreshing Tokens

To refresh this token, resubmit your configuration request detailed above. This will generate a new active token for you to use during your new session. If you are making this request RESTfully, a new token will only be generated after the old one has expired.