Skip to main content
Trellis supports two authentication methods for API access:
  1. Workspace API keys for trusted server-side integrations and MCP clients.
  2. 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

  1. Log in to the Trellis Dashboard.
  2. Open the workspace where the integration should operate.
  3. Go to Settings > Developer and open the Developer / API section.
  4. In API Keys, click Create Key.
  5. Give the key a clear name, such as “Operations MCP” or “Reporting worker”.
  6. 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.

​
Key scope

Each API key belongs to one workspace. Trellis rejects requests where the URL workspace does not match the key workspace, even if the same user belongs to multiple workspaces.
ScopeBehavior
WorkspaceThe key can only access the workspace where it was created
Server-side onlyDo not expose the key in browser or mobile client code
RevocableRevoked keys stop working immediately
The same key format works for the Public REST API and Trellis MCP Server.

​
Revoking a key

  1. Go to Settings > Developer and open the Developer / API section.
  2. Find the key you want to revoke.
  3. Click Revoke.
  4. 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

MethodPathDescription
POST/api/v1/auth/tokenAuthenticate with email and password
POST/api/v1/auth/refreshRefresh an expired access token
GET/api/v1/auth/meGet 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.