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

# Authentication

> How to authenticate with the TimelinesAI API

# Authentication

The TimelinesAI API uses Bearer token authentication. Every request must include your API token in the `Authorization` header.

## Getting your API token

**1. Sign in to TimelinesAI**

Go to [app.timelines.ai](https://app.timelines.ai)

**2. Open API settings**

Navigate to **Integrations** → **Public API**

**3. Copy your token**

Your token is displayed on this page. Click **Copy** to copy it.

## Using your token

Include the token in the `Authorization` header of every request:

```
Authorization: Bearer YOUR_API_TOKEN
```

### Example request

```bash cURL theme={null}
curl -X GET "https://app.timelines.ai/integrations/api/chats" \
  -H "Authorization: Bearer 4d2d0239-e28c-4f4a-8a4d-3a3ca40056b8"
```

```javascript JavaScript theme={null}
const response = await fetch('https://app.timelines.ai/integrations/api/chats', {
  headers: {
    'Authorization': 'Bearer 4d2d0239-e28c-4f4a-8a4d-3a3ca40056b8'
  }
});
```

```python Python theme={null}
import requests

response = requests.get(
    'https://app.timelines.ai/integrations/api/chats',
    headers={'Authorization': 'Bearer 4d2d0239-e28c-4f4a-8a4d-3a3ca40056b8'}
)
```

## Token security

> [!WARNING]
>
> Your API token provides full access to your workspace. Treat it like a password.

### Best practices

> [accordion] Use environment variables
>
> Never hardcode tokens in your source code. Use environment variables:
>
> ```bash theme={null}
> export TIMELINESAI_API_TOKEN="your-token-here"
> ```
>
> ```javascript theme={null}
> const token = process.env.TIMELINESAI_API_TOKEN;
> ```

> [accordion] Don't commit tokens to Git
>
> Add your environment files to `.gitignore`:
>
> ```
> .env
> .env.local
> .env.*.local
> ```

> [accordion] Rotate tokens if compromised
>
> If you suspect your token has been exposed, generate a new one immediately from the API settings page.

> [accordion] Use server-side only
>
> Never expose your API token in client-side code (browsers, mobile apps). Always make API calls from your backend server.

## Error responses

### 401 Unauthorized

If your token is missing or invalid:

```json theme={null}
{
  "status": "error",
  "message": "Invalid or expired token"
}
```

**Common causes:**

* Missing `Authorization` header
* Token copied incorrectly (check for extra spaces)
* Token has been regenerated

### 403 Forbidden

If your token is valid but lacks permission:

```json theme={null}
{
  "status": "error",
  "message": "Access denied"
}
```

**Common causes:**

* Attempting to access resources from another workspace
* Feature not available on your plan

## Token scope

Your API token has access to:

| Resource | Access |
| - | - |
| Chats | Read & Write |
| Messages | Read & Write |
| Labels | Read & Write |
| Files | Read & Write |
| WhatsApp Accounts | Read only |
| Webhooks | Read & Write |

> [!NOTE]
>
> All operations are scoped to your workspace. You cannot access data from other TimelinesAI accounts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.