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 all subsequent requests

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

import requests

response = requests.post(
    "https://api.trellis.sh/v1/authenticate",
    headers={"X-API-Key": "your_api_key_here"},
    json={"email": "[email protected]"}
)

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

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.

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

​Obtaining an API key

​Authentication flow

​Step 1: Exchange API key for JWT

​Step 2: Use the JWT token

​Token expiration

​Error responses

Obtaining an API key

Authentication flow

Step 1: Exchange API key for JWT

Step 2: Use the JWT token

Token expiration

Error responses