Authentication and OAuth APIs

Information in your project — including specifics about users and runs, as well as application-level data — is protected by Epicenter.

The Authentication and OAuth APIs confirm that valid credentials are supplied, and then grant a session-specific access token. This token is required in order to call any of the other Epicenter APIs successfully.

There are two types of access tokens in Epicenter:

User access tokens are specific to an Epicenter author, team member, or end user. API calls using this kind of token have access to all of the data that that user has access to.
Project access tokens are created with the Public and Secret API keys for the project. API calls using this kind of token have access to all of the data in the project.

For additional background on authentication, tokens, and Epicenter project access, see the Project Access page.

The Authentication and OAuth APIs supports the following HTTP methods:

POST: Creating a user access token (Authentication)
POST: Creating a user access token with impersonation (Authentication)
POST: Creating a project access token (OAuth)

POST: Creating a Token

Use the Authentication API POST method to create a new token.

Creating a User Access Token

Method: POST

URI: /v2/authentication

Headers: Content-Type: application/json

Body:

JSON object with the userName and password, e.g. {"userName": "myUser@forio.com", "password": "myPassw0rd"}.
If this the userName for an end user, the account (Team ID in the Epicenter user interface) is also required.

Response Status:

201: successful creation of token
400: invalid syntax in request
401: invalid username or password

Response Body: JSON object with an access token, refresh token, and expiration.

Example:

curl -X POST \
    'https://api.forio.com/v2/authentication/' \
    --header 'Content-Type: application/json' \
    --data '{"userName": "myUser@forio.com", "password": "myPassw0rd", "account": "acme-simulations"}'

Example Response:

{
    "refresh_token": "eyJqdGkiOiJlOWNlYTVmZ",
    "access_token": "eyJhbGciOiJSUzI1NiJ9",
    "expires": 43199
}

Notes:

In the request body, if this the userName for an end user, the account (Team ID in the Epicenter user interface) is also required.
Typically the access_token is around 1000 characters. Examples in the Epicenter documentation use a much shorter version to improve readability of the code.
The expires field is the number of seconds until the tokens expire.

Creating a User Access Token with Impersonation

Typically you need a user's username and password to create a user access token. As a special case, it is possible for your project to impersonate an end user by creating a user access token for an end user, using only the project access token.

Impersonation is not common. Occasionally, you may want to provide functionality in your simulation for a facilitator to log in as if they were a particular end user, so that facilitators can help troubleshoot or explain any issues that the end users are facing.

Method: POST

URI: /v2/authentication

Headers:

Content-Type: application/json
Authorization: Bearer{project access token}

Body: JSON object with the userName and account for the end user to impersonate e.g. {"userName": "testUser", "account": "testGroup"}

Response Status:

201: successful creation of tokens
400: invalid syntax in request
401: invalid username or account

Response Body: JSON object with an access token, refresh token, and expiration.

Example:

curl -X POST \
    'https://api.forio.com/v2/authentication/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer bG8naW46dH9niW7zZWNgZXQ='
    --data '{"userName": "testUser", "account": "acme-simulations"}'

Example Response:

{
    "refresh_token": "eyJqdGkiOiJlOWNlYTVmZ",
    "access_token": "eyJhbGciOiJSUzI1NiJ9",
    "expires": 43199
}

Notes:

The value of account is the Team ID for the team to which this end user belongs.
See Creating a project access token, below, for how to create the project access token used in the Authorization header.
Typically the access_token is around 1000 characters. Examples in the Epicenter documentation use a much shorter version to improve readability of the code.
The expires field is the number of seconds until the tokens expire.

Creating a Project Access Token

Project access tokens are created with the Public and Secret API keys for the project. API calls using this kind of token have access to all of the data in the project.

To create a project access token:

Create or regenerate API keys for your project. See API Keys under Updating your settings.
Encode the string "PublicKey:SecretKey" in Base64. For example, you might enter JjYi1kZTY4ZTg4ZjQ4N2:c0wy-1mxFncQmh46D at http://www.base64encode.org.
Use the Epicenter OAuth API to create an access token.

Method: POST

URI: /v2/oauth/token

Headers:

Content-Type: application/x-www-form-urlencoded
Authorization: Basic{base64 encoding of PublicKey:SecretKey}

Body: grant_type=client_credentials

Response Status: 200 (successful creation of tokens), 400 (invalid syntax in request), 401 (invalid authorization header)

Response Body: JSON object with an access token and expiration.

Example:

curl -X POST \
    'https://api.forio.com/v2/oauth/token' \
    --header 'Content-Type: application/x-www-form-urlencoded'  \
    --header 'Authorization: Basic bG8naW46dH9niW7zZWNgZXQ=' \
    --data 'grant_type=client_credentials'

Example Response:

{
    "refresh_token": "eyJqdGkiOiJlOWNlYTVmZ",
    "access_token": "eyJhbGciOiJSUzI1NiJ9",
    "expires": 43199
}

Notes:

Typically the access_token is around 1000 characters. Examples in the Epicenter documentation use a much shorter version to improve readability of the code.
The expires_in field is the number of seconds until the tokens expire.