Skip to main content
The CRM API supports three authentication methods. Pick the one that fits your integration.

​
Authentication methods at a glance

MethodHeader / mechanismBest for
Browser sessionCookies set after login (same origin)Web app, same-origin fetch calls
Better Auth session tokenAuthorization: Bearer <session_token>Mobile or desktop clients using Better Auth
Personal CRM API tokenAuthorization: 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

MethodPathDescription
GET/api/api-tokensList active tokens (no secret returned).
POST/api/api-tokensCreate a token. Response includes secret once.
DELETE/api/api-tokens/:idRevoke a token.