Authentication

📘

NOTE

For Tetra Data Platform (TDP) versions 3.6.0 and higher, API_KEY authentication is no longer an option. For more information, see API_KEY Authentication Deprecation.

📘

Authentication and SSO

If your environment has single sign-on (SSO) activated and you’re using the login API (/login), 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 grant access to the TetraScience API.

JWT Authentication

To authenticate into the TetraScience API, do the following:

Create a JWT

You can create a JWT in the TDP by doing either of the following:

Pass the JWT as a Header

You can pass the JWT that you create as header in your API requests in two ways:

  • A custom header: ts-auth-token
  • A standard Authorization header, as a bearer token (for example, Authorization Bearer [token])

You must also provide your organization slug in the x-org-slug header.

JWT Payload Schema Example

The following is an example of a JWT payload schema:

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

Retrieving a JWT as ats-auth-token Custom Header

To retrieve the ts-auth-token, use the login API ( /login). The login API requires the following parameters in the POST request body:

  • "email"
  • "password"
  • (For organizations that belong to a TDP tenant only) “subdomain"

📘

NOTE

The “subdomain" value is the subdomain listed in your TDP deployment’s URL path.

/login API POST Request Examples

The following are example JSON POST requests to the following endpoint: https://api.tetrascience.com/login

For Tetra Hosted Deployments

{
    "email": "[email protected]",
    "password": "mySperSecretPassword",
    "subdomain": "acme"
}

For Customer Hosted Deployments

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

Response Results

The following are examples of result payloads and authenticated headers.

Result Payload Example

{
  "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 Example

{
--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",
}