Authentication

Status: Beta Companion docs: Get started · Configuration · Authentication API

Give the SDK one Trinitite API key. It adds the bearer token to each platform request for you. The key also selects an account and carries permissions, so the service can keep each request inside the right organization.

Set your key

Put the key in an environment variable. Do not place it in source code.

export TRINITITE_API_KEY="trnt_live_replace_me"

Then create the client:

from trinitite import Trinitite

tr = Trinitite()
organization = tr.organization()

if not organization.ok:
    raise RuntimeError(organization.body)

Trinitite() reads TRINITITE_API_KEY. The SDK sends it as:

Authorization: Bearer trnt_live_replace_me

It also adds an X-Trinitite-Client header. This identifies the Python SDK, or your app when you set AppInfo.

Match the key to the environment

The SDK accepts three environment names. Each one has its own key prefix.

SDK environment	Key prefix	Default API address
prod	trnt_live_	https://api.trinitite.ai
test	trnt_test_	http://localhost:3000
dev	trnt_dev_	http://localhost:3000

Production is the default:

from trinitite import Trinitite

tr = Trinitite()  # env="prod"

Set non-production values together:

export TRINITITE_API_KEY="trnt_test_replace_me"
export TRINITITE_ENV="test"
export TRINITITE_BASE_URL="https://your-test-control-plane.example"

from trinitite import Trinitite

tr = Trinitite()

You can also pass the environment directly:

from trinitite import Trinitite

tr = Trinitite(
    env="test",
    api_key="trnt_test_replace_me",
    base_url="https://your-test-control-plane.example",
)

If the prefix and environment do not match, construction raises EnvironmentMismatchError. This stops a test key from reaching production by mistake.

from trinitite import EnvironmentMismatchError, Trinitite

try:
    tr = Trinitite(env="prod", api_key="trnt_dev_replace_me")
except EnvironmentMismatchError as error:
    print(error)

Create and protect keys

Create keys in the dashboard or with POST /auth/api-keys from an authenticated dashboard session. The create request requires an environment and can also set a name, permissions, features, and an expiry.

The raw key is returned when it is created. Store it in a secret manager or protected environment variable. The service stores a hash for later checks.

Use separate keys for:

• Production services
• Test and CI jobs
• Local development
• Apps that need different permissions

This split helps AI teams move faster without sharing one powerful secret across every service. It also limits the work a leaked key can perform.

API keys and provider credentials are different

Your Trinitite key authenticates your app to Trinitite. A provider credential lets the proxy call a model provider.

from trinitite import Trinitite

tr = Trinitite()

response = tr.client(
    "openai",
    credential="cred_openai_prod",
).chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize ticket 4821."}],
)

The SDK sends the Trinitite key in Authorization. It sends the stored provider credential ID in X-Trinitite-Credential-Id. The provider's raw key does not need to appear in this call.

Check authentication safely

Use the organization read as a small startup check:

from trinitite import Trinitite

tr = Trinitite()
response = tr.organization()

if response.status == 401:
    raise RuntimeError("The Trinitite API key is missing or invalid.")
if response.status == 403:
    raise RuntimeError("The key does not have permission for this request.")
if not response.ok:
    raise RuntimeError(f"Trinitite returned HTTP {response.status}.")

The SDK returns normal 4xx responses to your code. It does not retry them because they need a key, permission, or request change.

Where to go next

• Configuration: set timeouts, retries, regions, and app identity.
• Scopes and assets: bind model and tool access to one clear goal.
• Provider credentials API: store model-provider credentials for proxy calls.