# Authentication

The Engine API is authorized through OAuth 2.0 . You will need to pass a bearer token together with each API call. This bearer token is obtained by authenticating towards Auth0, and remains valid for 24h (see section below on reusing tokens). The token is used for all subsequent calls to the Engine API, until it expires.

# Obtaining a bearer token

Tokens are obtained through the Auth0 authentication endpoint (<AUTH0_DOMAIN>/oauth/token). You will need to authenticate through the Client Credentials grant (M2M), using your unique client ID and client secret (shared with you by Relu, contact us if you haven't received one yet).

The Auth0 domain depends on which region you selected.

for EU use https://vpengine.eu.auth0.com
for US https://vpengine.us.auth0.com

The code snippet below provides an example of how to obtain a token for the EU region.

curl --request POST \
  --url "https://vpengine.eu.auth0.com/oauth/token" \
  --header "Content-Type: application/json" \
  --data '{ "grant_type": "client_credentials", "audience": "virtualpatientengine.com", "client_id": "<YOUR_CLIENT_ID>", "client_secret": "<YOUR_CLIENT_SECRET>" }'

$json = @" 
  {  
    "grant_type": "client_credentials",
    "audience": "virtualpatientengine.com",
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>"
  } 
"@

curl --request POST --url "https://vpengine.eu.auth0.com/oauth/token" --header "Content-Type: application/json" --data $json

var axios = require('axios');

axios
  .post('https://vpengine.eu.auth0.com/oauth/token', {
    grant_type: 'client_credentials',
    audience: 'virtualpatientengine.com',
    client_id: '<YOUR_CLIENT_ID>',
    client_secret: '<YOUR_CLIENT_SECRET>',
  })
  .then((response) => {
    console.log(response.data);
  });

import http.client
import json

conn = http.client.HTTPSConnection("vpengine.eu.auth0.com")

headers = {"content-type": "application/json"}
payload = {
    "grant_type": "client_credentials",
    "audience": "virtualpatientengine.com",
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
}

conn.request("POST", "/oauth/token", json.dumps(payload), headers)

response = conn.getresponse()
print(response.read().decode())

You can find more information on how to generate this token in the Auth0 documentation. The result will look like this:

{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

# Using the token

To make HTTP requests to the Relu® Hosted Engine API, you will need to include the access token (access_token) from the response as an authorization header. You can use the test route below to test whether the token is working. The example uses the 24.06 version of the Engine, hosted in the EU region.

curl --request GET \
  --url "https://eu.virtualpatientengine.com/24.06/testAuth" \
  --header "Authorization: Bearer <YOUR_GENERATED_ACCESS_TOKEN>"

var axios = require('axios');

axios
  .get('https://eu.virtualpatientengine.com/24.06/testAuth', {
    headers: {
      "Authorization": "Bearer <YOUR_GENERATED_ACCESS_TOKEN>"
    }
  })
  .then((response) => {
    console.log(response.data);
  });

import http.client

conn = http.client.HTTPSConnection("eu.virtualpatientengine.com")

headers = {"Authorization": "Bearer <YOUR_GENERATED_ACCESS_TOKEN>"}

conn.request("GET", "/24.06/testAuth", headers=headers)

response = conn.getresponse()
print(response.read().decode())

In case of successful authentication, the route will respond with:

["You have been successfully authenticated"]

In case of a malformed, expired, or missing token, the API would respond with a 401 Unauthorized status code.

In the next section, you will find out how to use this token to submit your first job to the Engine API.

# Reusing tokens

The access tokens are valid for 24 hours. We ask you to cache and reuse the token until it nears expiry. This to avoid consuming unnecessary resources. The token expiry time can easily be read out from the response from Auth0, under the key expires_in. It can be used for all subsequent calls to the Engine API, until it expires.

While there is no strict limit at this point, we might introduce rate limiting in the future.