forio Toggle navigation

Project Access: Authorization and Authentication in Epicenter

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

To access your project using the Epicenter APIs, you need to send an access token.

Read more about:

Background

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. See Creating user access tokens, below.
    • For example, an end user without Facilitator privileges has access only to the runs that he has created or runs that are part of a game in which he is included. An end user with Facilitator privileges has access to all runs created by end users in his group, but not to runs created by end users in other groups.
    • User access tokens are recommended and usally are the only kind of token that you need.
    • 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 the project access token rather than the user's username and password. See Creating user access tokens with impersonation, below.
  • 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. See Creating project access tokens, below.
    • The most common use case for this is a project that displays a high score list. To construct the list, you need to read the score from all runs from all users from all groups in the project. No single user (whether Facilitator or not) has access to this information, so the API call to read the scores must use a project access token.
    • To create or reset your project's API keys, see the Project Settings for API keys.

#### Using an Access Token

There are two ways to pass in your acccess token:

  • Add the header Authorization: Bearer myAccessToken to your request.

    • The Epicenter REST APIs require you to explicitly create this token and add it to the header of each request yourself.
    • Other Epicenter APIs, like the API Adapters, do this for you when you log in.

  • Log in to the Epicenter UI, and send requests from the browser: Every time you log in to the Epicenter UI, the browser cookie epicenter.token is set with the user access token of the logged in user. Subsequent requests from the browser use this access token as part of each API request, and you do not need to pass in anything special in the request header. The token is valid as long as the user is logged in; the cookie is deleted when the user logs out of the Epicenter UI.

As best practices for using your access tokens:

  • Only make requests to the Epicenter APIs with the minimum privileges required. For example, if you are displaying a high score list, use the project access token (created with the project API keys) to request the high score data, but use the user access token (created with the user's username and password) to request any other information on the page, such as the name of the user.

  • When creating project access tokens, make sure that all requests that use your API keys are sent from the server-side, that is, from your Node.js code. (Client-side only projects are less secure as the API key is necessarily user readable.)


#### Creating a User Access Token

The easiest way to create a user access token is to log in to the Epicenter UI. The epicenter.token cookie has the user access token as its value. The token is valid as long as the user is logged in; the cookie is deleted when the user logs out of the Epicenter UI.

You can also create a user access token using the Epicenter Authentication API:

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": "acme-simulations"}

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.

**Working with Third Party End Users**

Although generally impersonation is not common, one use case for impersonation is if you have third party end users accessing your project.

End users created in a third party system can be added to Epicenter projects. (Contact us for more details on this option.)

If an end user has been created by a third party system, you cannot create a user access token for this end user (because the third party system, not Epicenter, is storing the end user's password). Instead, you should create a project access token and use that to impersonate the end user when the end user logs in.


#### Creating a Project Access Token
  1. Create or regenerate API keys for your project. See API Keys under Updating your settings.
  2. Encode the string "PublicKey:SecretKey" in Base64. For example, you might enter JjYi1kZTY4ZTg4ZjQ4N2:c0wy-1mxFncQmh46D at http://www.base64encode.org.
  3. 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.