Authentication - Trellis API

The Trellis API uses a two-step authentication flow:

Exchange your API key for a JWT token.
Use the JWT token to authenticate every subsequent request.

The JWT is valid for six hours; refresh by re-exchanging your API key when it expires.

Obtaining an API key

API keys are provisioned through the Trellis admin dashboard. Contact your organization administrator or reach out to Trellis support to obtain one.

Keep your API key secure. Do not expose it in client-side code or commit it to version control.

Authentication flow

Step 1: Exchange API key for JWT

To start a session, send your API key and the user’s email address to the authenticate endpoint.

cURL
Python
JavaScript

curl -X POST https://api.trellis.sh/v1/authenticate \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

import requests

response = requests.post(
    "https://api.trellis.sh/v1/authenticate",
    headers={"X-API-Key": "your_api_key_here"},
    json={"email": "user@example.com"}
)

data = response.json()
token = data["token"]

const response = await fetch("https://api.trellis.sh/v1/authenticate", {
  method: "POST",
  headers: {
    "X-API-Key": "your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "user@example.com" }),
});

const { token } = await response.json();

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "member_id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "org_abc123",
  "expires_at": "2025-01-11T18:00:00Z"
}

If the email address doesn’t exist in your organization, Trellis will automatically create a new user account.

Step 2: Use the JWT token

Include the JWT token in the Authorization header for all API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token expiration

JWT tokens expire 6 hours after they are issued. The expires_at field in the authentication response tells you exactly when. When a token expires, you’ll receive a 401 Unauthorized response. Simply re-authenticate to get a new token.

For long-running applications, implement token refresh logic that re-authenticates before the token expires.

Token identity (`jti`) and rate-limit buckets

Every JWT issued by /v1/authenticate carries a unique jti (JSON Web Token ID) claim — a v4 UUID generated at sign time. Trellis uses jti as the bucket key for rate limits and the WebSocket concurrent-connection cap. Practical implications:

Re-authenticating returns a fresh jti, so a new token resets every per-token throttle and concurrency slot.
Two services sharing one JWT also share its rate-limit and connection budgets. Issue separate tokens to separate them.
The jti is opaque — clients don’t need to inspect or echo it; just keep using the token string.

Error responses

Status	Error	Description
400	Invalid email format	The email address is not properly formatted
401	Missing X-API-Key header	No API key was provided
401	Invalid API key	The API key is incorrect or revoked
500	JWT signing not configured	Server-side configuration error

Getting Started

Documentation Index

​Obtaining an API key

​Authentication flow

​Step 1: Exchange API key for JWT

​Step 2: Use the JWT token

​Token expiration

​Token identity (jti) and rate-limit buckets

​Error responses

Obtaining an API key

Authentication flow

Step 1: Exchange API key for JWT

Step 2: Use the JWT token

Token expiration

Token identity (`jti`) and rate-limit buckets

Error responses