TetraScience uses a JSON Web Token (JWT) to grant access to the TetraScience API as part of the OAuth 2.0 framework.

🚧
IMPORTANT
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.

TetraScience API Authentication

To authenticate into the TetraScience API, do the following:

Create a JWT.
Pass the JWT as a header in your API request.

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

Step 1: Create a JWT

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

Use the personal token from your My Account page, which is configurable up to 24 hours.
-or-
Create a Service User account and generate a token for it.

Step 2: Pass the JWT as a Header in Your API Request

You can pass the JWT that you create as header in your API requests by doing either of the following:

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

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

`ts-auth-token` Authenticated Header Example

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

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

`Authorization: Bearer` Authenticated Header Example

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

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

Retrieving a JWT as a`ts-auth-token` Custom Header

To retrieve the ts-auth-token, use the Login User API endpoint (/login). This 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 Login User API endpoint (/login).

For Tetra Hosted Deployments

{
    "email": "akader+acme@tetrascience.com",
    "password": "mySperSecretPassword",
    "subdomain": "acme"
}

For Customer Hosted Deployments

{
  email: "userid@tetrascience.com", 
  password: "#######"
}

Response Results

The following is an example result payload from the Login User API endpoint (/login).

📘
NOTE
The returned tokens include an expiration time that's set by the system administrator for your tenant. For more information, see Tenant Settings.

{
  "id": "<your id>",
  "firstName": "John",
  "lastName": "Smith",
  "email": "userid@tetrascience.com",
  "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>"
}