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

# Authentication

> Authenticate to the self-hosted CRM API with session cookies, Bearer tokens, or Personal CRM API tokens.

The CRM API supports three authentication methods. Pick the one that fits your integration.

## Authentication methods at a glance

| Method | Header / mechanism | Best for |
| - | - | - |
| Browser session | Cookies set after login (same origin) | Web app, same-origin fetch calls |
| Better Auth session token | `Authorization: Bearer <session_token>` | Mobile or desktop clients using Better Auth |
| Personal CRM API token | `Authorization: Bearer bos_crm_<secret>` | Server-to-server integrations, scripts, CI/CD |

All three methods resolve to a user identity. RBAC rules apply the same way regardless of how you authenticate.

***

## Browser session (cookies)

When a user signs in through the BasicsOS web UI, the server sets session cookies. Any same-origin request from the browser automatically includes these cookies.

```js theme={null}
// Same-origin fetch — cookies are sent automatically
const res = await fetch("/api/contacts");
const contacts = await res.json();
```

No `Authorization` header is needed. This is the default auth for the built-in web app.

***

## Better Auth session token

Some clients (mobile apps, desktop apps) obtain a session token from Better Auth during login. Pass it as a Bearer token:

```bash theme={null}
curl https://your-app.up.railway.app/api/contacts \
  -H "Authorization: Bearer <session_token>"
```

The server maps this token to the same session the browser uses internally.

***

## Personal CRM API token

For programmatic access — scripts, server-to-server integrations, CI/CD pipelines — create a Personal CRM API token in the BasicsOS web app under **Settings > Personal CRM API tokens**.

* **Prefix:** `bos_crm_`
* **Scoping:** The token acts as the user who created it. RBAC rules apply exactly as they do in the web UI.
* **Storage:** The full token is shown once at creation. Store it securely; it cannot be retrieved again.

```bash theme={null}
curl https://your-app.up.railway.app/api/contacts \
  -H "Authorization: Bearer bos_crm_your_token_here"
```

> [!TIP]
>
> Personal CRM API tokens are created in-app, not through the Basics Gateway. They are specific to your self-hosted server.

***

## Token management API

Manage Personal CRM API tokens programmatically. These endpoints require **session-based auth** (browser cookies or Better Auth session token) — you cannot use a Personal CRM API token to create or revoke other tokens.

> [!NOTE]
>
> Only users with **records.write** permission (or admins with full access) can manage API tokens.

### List active tokens

```
GET /api/api-tokens
```

Returns an array of token metadata. The token secret is **never** included in list responses.

```bash theme={null}
curl https://your-app.up.railway.app/api/api-tokens \
  -H "Authorization: Bearer <session_token>"
```

**Response:**

```json theme={null}
[
  {
    "id": "tok_abc123",
    "name": "CI pipeline",
    "created_at": "2025-03-15T10:00:00Z",
    "last_used_at": "2025-03-22T14:30:00Z"
  }
]
```

### Create a token

```
POST /api/api-tokens
```

**Request body:**

```json theme={null}
{
  "name": "My integration"
}
```

**Response:**

```json theme={null}
{
  "id": "tok_def456",
  "name": "My integration",
  "token": "bos_crm_live_a1b2c3d4e5f6...",
  "created_at": "2025-03-23T08:00:00Z"
}
```

> [!TIP]
>
> The `token` field is returned **only** in the creation response. Copy and store it immediately.

### Revoke a token

```
DELETE /api/api-tokens/:id
```

```bash theme={null}
curl -X DELETE https://your-app.up.railway.app/api/api-tokens/tok_abc123 \
  -H "Authorization: Bearer <session_token>"
```

Returns `204 No Content` on success.

### Token management summary

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/api-tokens` | List active tokens (no secret returned). |
| `POST` | `/api/api-tokens` | Create a token. Response includes secret once. |
| `DELETE` | `/api/api-tokens/:id` | Revoke a token. |


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