Skip to main content

Configure the SDK

This page covers the configuration steps required to run the Treble SDK in your environment. It describes how to keep your installation up to date, how to authenticate using either a .cred file or a credential string, and how to resolve SSL certificate errors that may arise on corporate or proxy-managed networks.

Update the SDK​

There are two ways to update your installation of the SDK to the newest available version: either by using the management portal, or from within an environment already running the SDK.

Update from the management portal​

Navigate to the management portal and use the login credentials you created when your account was set up to enter the website. Download the installation file to your chosen directory, and install the .whl file inside your python environment by running the following code in your terminal:

pip install treble_tsdk-<version>-py3-none-any.whl

Update from within an existing environment​

First, initialise the SDK and specify the base directory.

from treble_tsdk import treble
tsdk = treble.TSDK()

from pathlib import Path
base_dir = Path.home()/"SDK_versions"
print(base_dir)

Using the SDK's built-in command, fetch the latest .whl package:

tsdk.download_update(base_dir)

Within the Python environment where the SDK is installed, run the following to install the update:

%pip install {base_dir}/treble_tsdk-<version>-py3-none-any.whl

Credentials​

Save your credential file to the correct directory before initializing the SDK. The TSDK class is the entry point for all SDK interactions — instantiating it loads your credentials and checks for available updates. Keep your SDK installation up to date to ensure access to the latest features and fixes.

Login using .cred file​

The recommended authentication method is using the .cred file downloaded from the management portal. When you instantiate TSDK(), the SDK searches the following default locations depending on your operating system:

OSDefault path
Windows%HOME%/AppData/Local/treble/tsdk/tsdk.cred
Linux~/.config/treble/tsdk.cred
macOS~/.config/treble/tsdk.cred

Place your .cred file in the appropriate directory, then initialize the SDK:

tsdk = treble.TSDK()

To use a custom file path instead:

tsdk = treble.TSDK(treble.TSDKCredentials.from_file("<path/to/file.cred>"))

Login using credential string​

You can also authenticate by passing your credential string directly:

tsdk = treble.TSDK(treble.TSDKCredentials(""))

Alternatively, set the credential string as an environment variable named TSDK_CREDENTIALS. The SDK detects and uses this variable automatically, so no argument is required at initialization. To set the variable in a Linux or macOS terminal:

export TSDK_CREDENTIALS=""

Then initialize the SDK as normal:

tsdk = treble.TSDK()

Login using SSO Enterprise​

If your organization uses SSO Enterprise authentication, you will authenticate with the Treble SDK using an SSO token instead of a .cred file.

Your SSO token is available on the management portal under the Treble SDK page.

Prerequisites
  • Your organization has SSO Enterprise enabled. If you are unsure, contact your account administrator or support@treble.tech.

Obtaining your SSO token​

  1. Log in to the management portal.
  2. Navigate to the Treble SDK page.
  3. Your SSO token is displayed under SSO credentials. Click Copy token to copy it to your clipboard.

Authenticating the SDK​

There are three ways to authenticate with SSO Enterprise.

Option 1: Set the SSO token as an environment variable​

Set the TSDK_SSO_TOKEN environment variable to the token from the management portal:

export TSDK_SSO_TOKEN=<your_sso_token>

Then initialize the SDK without any arguments:

from treble_tsdk import treble

tsdk = treble.TSDK()

The SDK will automatically detect and use the SSO token from the environment variable.

Refreshing an expired session​

If your session expires during a long-running process, obtain a fresh token from the management portal, update the environment variable, and call:

tsdk.refresh_authentication()
Option 2: Pass the SSO token directly when initializing the SDK​

Pass the token programmatically using TSDKCredentials.sso():

from treble_tsdk import treble

tsdk = treble.TSDK(treble.TSDKCredentials.sso('<your_sso_token>'))

This approach is useful when you want to manage credentials explicitly in your code, for example when switching between different environments or accounts.

Refreshing an expired session​

If your session expires during a long-running process, obtain a fresh token from the management portal and pass it directly:

tsdk.refresh_authentication(treble.TSDKCredentials.sso('<your_new_sso_token>'))
Option 3: Interactive login (device code flow)​

Authenticate with treble.login() — an interactive device code flow.

from treble_tsdk import treble

tsdk = treble.login()

When you run this, the SDK will:

  1. Print a URL and a one-time code to your terminal.
  2. You open the URL in any browser and enter the code.
  3. Authenticate with your organization's SSO provider.
  4. The SDK automatically receives short-lived tokens and initializes.

The terminal output looks like this:

============================================================
  Treble SDK — Device Login
============================================================

  Open: https://treble-prod.eu.auth0.com/activate?user_code=XXXX-XXXX

  Code expires in 5 minutes.
  Waiting for authentication.....
  ✓ Authentication successful!
============================================================
Refreshing an expired session​

If your session expires, call refresh_authentication() with no arguments. The SDK detects that you authenticated via the device code flow and automatically re-runs the interactive login:

tsdk.refresh_authentication()

This will print a new device code URL in your terminal — open it in your browser and authenticate again, just like the first time.

When to use which method
  • Environment variable or programmatic token (Options 1 & 2) — suited for automated scripts, CI/CD pipelines, or when you want to reuse a token across multiple runs.
  • Interactive login (Option 3) — suited for local development, notebooks, or shared machines where you don't want to manage tokens manually.

Authorized redirect URIs​

Add the following URIs to the Authorized redirect URIs (sometimes called "Allowed callback URLs") in your identity provider's OAuth client configuration:

Redirect URI
https://treble-prod.eu.auth0.com/login/callback
https://manage.treble.tech
https://auth.treble.tech/login/callback
caution

These URIs allow Treble's authentication service (Auth0) to complete the SSO handshake with your identity provider. Without them, SSO login will fail with a redirect error.

Administrator notes​

Users must be added to the admin portal before they can authenticate with the SDK.

The onboarding steps are:

  1. Add the user in the admin portal with their corporate email (the same email used by your identity provider).
  2. Grant the user SDK product access.
  3. The user runs treble.login() or uses an SSO token.

Troubleshooting​

Token not recognized​

Make sure you have copied the full token from the management portal. The token is a long Base64-encoded string — verify that no characters were truncated when copying.

Session expired​

If you receive an authentication error, your SSO session may have expired. Log in to the management portal again and copy a fresh token. Or you can use tsdk.refresh_authentication() to refresh the SSO token.

Wrong environment variable name​

Double-check that you are using TSDK_SSO_TOKEN (not TSDK_CREDENTIALS). The two environment variables correspond to different authentication methods and are not interchangeable.

SSO login fails with redirect error​

If the device code or SSO login redirects to an error page, your identity provider may not have the correct callback URIs configured. See Authorized redirect URIs above and ensure the redirect URI for your environment is whitelisted.

"User does not have access to the SDK"​

This means the user has not been provisioned in the management portal, or their SDK product access has not been granted. See Administrator notes above.

SSL Errors​

When connecting to the Treble SDK on a corporate network, you might experience errors with the SSL connection. This is caused by firewalls or proxy servers set up by the network administrators of the organization. Instead of connecting to the Treble SDK endpoint, the SDK has to go through a middle server which the network layer of the SDK client does not recognize.

Fixes​

There are a few solutions we can try to mitigate the issue before we involve your local network administartor.

Prerequisites​

Ensure you have Python 3.10+ installed.

Confirm that your connection to https://stapi.treble.tech is secure in your web browser.

Install the truststore Python package:​

pip install truststore

Then follow the instructions for your operations system:

Choose one of the following methods:​

  • Option A: Set the environment variable TSDK_USE_TRUSTSTORE=1 before importing the SDK.
  • Option B: Add the following lines to your script before starting the SDK session:
import truststore
truststore.inject_into_ssl()

If these instuctions do not solve your SSL issues, please consult with your network administrators and the Treble support team to resolve the problem.