Authentication

📘

NOTE

In previous versions of the software, we offered the API_KEY as an alternate authentication option. The API_KEY is now deprecated.

📘

Authentication and SSO

If your environment has single sign-on (SSO) activated and you’re using the /login API endpoint, you must get your JSON Web Token (JWT) from your TDP account page. Otherwise, the following procedure won’t work.

TetraScience uses a JSON Web Token (JWT) to allow access to the API. You can create a new JWT on our platform in two ways:

• You can use the four-hour personal token that is available in your My Account page.
  -or-
• For a longer-lasting token, you can create a Service User and generate a token for it.

The JWT can be passed as header in two ways:

• as a custom header ts-auth-token
• in the standard Authorization header, as a bearer token (eg. Authorization Bearer [token])

You will also need to provide your org slug in the x-org-slug header.

An example of the JWT payload schema:

{
  tsTokenSchemaVersion: 1,
  authStacks: {
    informatics : {
      systemRoles: [],
      userId: <user_id>,
      organizations: {
        <organization_id>: {
          slug: <org_slug>,
          roles: [
             <role based access control...>
          ]
        }
      }
    }
  }
}

The ts-auth-token can be retrieved by using the login API ( /login ), with email and password provided in the POST request body.

For example, POST to https://api.tetrascience.com/login

{
  email: "[email protected]", 
  password: "#######"
}

Once authenticated, your result payload should look something like:

{
  "id": "<your id>",
  "firstName": "John",
  "lastName": "Smith",
  "email": "[email protected]",
  "systemRole": "ts-admin",
  "status": "active",
  "roles": [
    {
      "id": "<your id>",
      "userId": "<your user id>",
      "organizationId": "<your organization id>",
      "orgSlug": "<your organization's slug>",
      "orgName": "<your organization's name>",
      "role": "<your role>"
    }
  ],
  "token": "<JSON web token>"
}

Authorization: Bearer Authenticated headers examples:

{
--header 'Authorization: Bearer <JWT Token>'\
--header 'x-org-slug: <YOUR ORGANIZATION>' \
}

{
 "Authorization: "Bearer <JSON web token>",
 "x-org-slug": "diagnostic"
}

ts-auth-token Authenticated headers examples:

{
--header 'ts-auth-token: <JWT Token>' \
--header 'x-org-slug: <YOUR ORGANIZATION>' \
}

{
  "ts-auth-token": "<JSON web token>",
  "x-org-slug": "tetrascience",
}