📘

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:

• 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.

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.

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. The tokens returned through this method include an expiration time that's set by the system administrator for your tenant. For more information, see Tenant Settings.

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