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:

1. Create a JWT.
2. 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 ats-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": "[email protected]",
    "password": "mySperSecretPassword",
    "subdomain": "acme"
}

For Customer Hosted Deployments

{
  email: "[email protected]", 
  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": "[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>"
}