> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trellistech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Workspace API keys, programmatic session authentication, and security guidance for Trellis integrations.

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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer trls_acmevaca_abc123..." \
    https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks
  ```

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

### Obtain an API key

1. Log in to the [Trellis Dashboard](https://app.trellistech.com).
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.

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

### 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.

| Scope            | Behavior                                                   |
| ---------------- | ---------------------------------------------------------- |
| Workspace        | The key can only access the 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](/api-reference/public-rest-api) and [Trellis MCP Server](/api-reference/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

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"operator@example.com","password":"YOUR_PASSWORD"}' \
  "https://app.trellistech.com/api/v1/auth/token"
```

Response:

```json theme={null}
{
  "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": "operator@example.com",
    "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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  "https://app.trellistech.com/api/v1/auth/me"
```

Response:

```json theme={null}
{
  "user": {
    "id": "11111111-1111-4111-8111-111111111111",
    "email": "operator@example.com",
    "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   |

<Note>
  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`.
</Note>

## 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.