Authentication

UseBelha supports three authentication methods: browser cookies, API keys, and bearer tokens.

Authentication Methods

Cookie Session

For browser-based dashboard access. Automatic after sign-in.

API Key

For server-to-server integration. Created in dashboard.

Bearer Token

For non-cookie clients. Pass session token in header.

Using API Keys (Recommended for SDK)

Create an org-scoped API key in the Organization settings.

bash

curl -X POST "https://dev.usebelha.com/api/agents?template=tpl_search&action=chat" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{"sessionId": "test", "message": "Hello"}'

If your API key is not org-scoped, include the organization ID:

bash

curl -X GET "https://dev.usebelha.com/api/agents" \
  -H "x-api-key: your-api-key-here" \
  -H "x-organization-id: org_xxxxx"

Using Bearer Tokens

Pass your session token in the Authorization header:

bash

curl -X GET "https://dev.usebelha.com/api/agents" \
  -H "Authorization: Bearer your-session-token"

Demo Mode

For testing without authentication, use demo mode:

Demo Mode Limitations

• Rate limited to 10 requests/minute
• Can only chat with templates (no agent creation)
• Uses tenant_demo tenant ID
• No access to Knowledge API

bash

# Dashboard demo mode
https://dev.usebelha.com/dashboard/templates?token=demo

# API demo mode
curl -X POST "https://dev.usebelha.com/api/agents?template=tpl_basic&action=chat" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: tenant_demo" \
  -d '{"sessionId": "test", "message": "Hello"}'

Organizations (Multi-Tenancy)

UseBelha uses organizations for multi-tenancy. Each user belongs to one or more organizations, and all agents/data are scoped to an organization.

Sign up at /signup
A default organization is auto-created on first login
Manage organizations at /dashboard/org
Create org-scoped API keys for SDK access

System Automations

For cron jobs and webhooks, use the dedicated endpoint POST /api/internal/run-automation. This endpoint requires an API key and runs as a system caller (enforced by route policy).

bash

curl -X POST "https://dev.usebelha.com/api/internal/run-automation" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -H "x-trigger-type: schedule" \
  -H "x-automation-id: nightly-run" \
  -d '{"target":"ag_xxx","input":{"message":"Run nightly job"},"idempotencyKey":"nightly-2025-01-01"}'

Note: Agents default to allowedCallers=["user"]. To enable automations, set allowedCallers to include system.

Protected Endpoints

Endpoint	Auth Required	Demo Mode
`GET /api/agents/templates`	No (public)	Yes
`POST /api/agents?action=chat`	Yes*	Yes (with x-tenant-id)
`GET/POST/DELETE /api/agents`	Yes	No
`GET/POST/DELETE /api/knowledge`	Yes	No
`POST /api/internal/run-automation`	Yes (API key)	No

* Template chat allows demo mode with rate limits