Authentication

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.

// 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:

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.

curl https://your-app.up.railway.app/api/contacts \
  -H "Authorization: Bearer bos_crm_your_token_here"

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.

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.

curl https://your-app.up.railway.app/api/api-tokens \
  -H "Authorization: Bearer <session_token>"

Response:

[
  {
    "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:

{
  "name": "My integration"
}

Response:

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

The token field is returned only in the creation response. Copy and store it immediately.

Revoke a token

DELETE /api/api-tokens/:id

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.

Overview

API reference

Authentication methods at a glance

Browser session (cookies)

Better Auth session token

Personal CRM API token

Token management API

List active tokens

Create a token

Revoke a token

Token management summary

​Authentication methods at a glance

​Browser session (cookies)

​Better Auth session token

​Personal CRM API token

​Token management API

​List active tokens

​Create a token

​Revoke a token

​Token management summary

Authentication methods at a glance

Browser session (cookies)

Better Auth session token

Personal CRM API token

Token management API

List active tokens

Create a token

Revoke a token

Token management summary