Authentication

Trellis supports two authentication methods for API access:

Workspace API keys for trusted server-side integrations and MCP clients.
Programmatic session tokens for email/password authentication flows.

Workspace API keys

Send the workspace API key as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer trls_acmevaca_abc123..." \
  https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks

const response = await fetch('https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks', {
  headers: {
    Authorization: `Bearer ${process.env.TRELLIS_API_KEY}`,
  },
})

Obtain an API key

Log in to the Trellis Dashboard.
Open the workspace where the integration should operate.
Go to Settings > Developer and open the Developer / API section.
In API Keys, click Create Key.
Give the key a clear name, such as “Operations MCP” or “Reporting worker”.
For a server integration, select each workspace the key should access.
Copy the key immediately and store it in your server-side secret manager.

API keys are only displayed once. If you lose a key, revoke it and create a new one.

Only an active Trellis workspace administrator can create, update, or revoke keys. A key is automatically bound to the current workspace. There is no workspace selector, and an external integration cannot mint keys or grant itself access to another workspace.

Key scope

Each API key has exactly one owner workspace where administrators manage it. Trellis rejects requests when the workspace in the URL is not that owner workspace. Call GET /api/v1/workspaces with the key to discover its owner workspace id and display name. Use that id in workspace-scoped API requests. To change an existing server integration key, open its Permissions action in Settings > Developer. You can update its scopes without replacing or revealing the key. Its workspace cannot be changed.

Scope	Behavior
Workspace scope	The key can access only the current workspace where it was created
Server-side only	Do not expose the key in browser or mobile client code
Revocable	Revoked keys stop working immediately

The same key format works for the Public REST API and Trellis MCP Server.

Revoking a key

Go to Settings > Developer and open the Developer / API section.
Find the key you want to revoke.
Click Revoke.
Confirm the action.

Any client using the revoked key will receive 401 Unauthorized.

Programmatic session authentication

Use the auth endpoints to authenticate with email and password and receive a session token. This is useful for integrations that run under a specific Trellis user account.

Create a session

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"YOUR_PASSWORD"}' \
  "https://app.trellistech.com/api/v1/auth/token"

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "YOUR_REFRESH_TOKEN",
  "tokenType": "bearer",
  "expiresIn": 3600,
  "expiresAt": "2026-06-23T18:00:00.000Z",
  "user": {
    "id": "11111111-1111-4111-8111-111111111111",
    "email": "[email protected]",
    "fullName": "Ari Operator",
    "avatarUrl": null,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "lastSignInAt": "2026-06-23T17:00:00.000Z"
  }
}

Use the accessToken as a Bearer token for subsequent requests:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks"

Refresh a session

Access tokens expire. Use the refresh token to get a new access token without re-authenticating:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"YOUR_REFRESH_TOKEN"}' \
  "https://app.trellistech.com/api/v1/auth/refresh"

The response has the same shape as POST /auth/token. Store the new refreshToken for subsequent refreshes.

Get the authenticated profile

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  "https://app.trellistech.com/api/v1/auth/me"

Response:

{
  "user": {
    "id": "11111111-1111-4111-8111-111111111111",
    "email": "[email protected]",
    "fullName": "Ari Operator",
    "avatarUrl": null,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "lastSignInAt": "2026-06-23T17:00:00.000Z"
  }
}

Auth endpoints summary

Method	Path	Description
`POST`	`/api/v1/auth/token`	Authenticate with email and password
`POST`	`/api/v1/auth/refresh`	Refresh an expired access token
`GET`	`/api/v1/auth/me`	Get the authenticated user profile

The auth endpoints authenticate existing Trellis user profiles. They do not create new users or workspace memberships. Workspace API keys (trls_...) do not have user profiles and will receive 401 from GET /auth/me.

Security best practices

Store keys and tokens in environment variables or a secret manager.
Never commit a key to source control.
Rotate keys periodically.
Create separate keys for separate systems so you can revoke one integration without disrupting others.
Use explicit user confirmation before any connected client creates tasks, updates records, or sends messages.
For programmatic sessions, store refresh tokens securely and refresh proactively before the access token expires.

Start Here

Setup & Operations Guides

Daily Work

AI Agent & Knowledge

Automations & Workflows

Business & Reporting

Settings & Admin

Troubleshooting

Connect Your PMS

Field Operations Integrations

Finance & Spend

API Reference

Changelog

Workspace API keys

Obtain an API key

Key scope

Revoking a key

Programmatic session authentication

Create a session

Refresh a session

Get the authenticated profile

Auth endpoints summary

Security best practices

​Workspace API keys

​Obtain an API key

​Key scope

​Revoking a key

​Programmatic session authentication

​Create a session

​Refresh a session

​Get the authenticated profile

​Auth endpoints summary

​Security best practices

​Related articles

Workspace API keys

Obtain an API key

Key scope

Revoking a key

Programmatic session authentication

Create a session

Refresh a session

Get the authenticated profile

Auth endpoints summary

Security best practices

Related articles