Authentication

Senda supports two authentication methods. API keys for server-to-server and widget integrations, and JWT cookies for the SPA.

API Keys

API keys use the format sk_live_ followed by 64 hex characters:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8

Include the key in the Authorization header:

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  https://senda.telar.ai/api/v1/agents

Scopes

Each API key has a set of scopes that control what it can access:

Scope	Grants Access To
chat	/v1/chat/* — Send messages, read history
agents	/v1/agents/* — List and read agent details
files	/v1/knowledge/* — Upload and list documents
actions	/v1/actions/* — List and execute actions
analytics	/v1/usage — Read consumption metrics

Key Management

API keys are managed via the /v1/keys endpoints (requires JWT authentication, not API key):

# Create a key
curl -X POST https://senda.telar.ai/api/v1/keys \
  -H "Cookie: Senda-Token=YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "scopes": ["chat", "agents"]}'

# Response (key shown ONCE)
{
  "id": "ak_abc123",
  "key": "sk_live_a1b2c3d4...",
  "prefix": "sk_live_a1b2c3d4",
  "message": "API key created. Save it now — it cannot be retrieved again."
}

Security Best Practices

warning

• Never expose API keys in frontend code. Use the Widget which handles authentication securely.
• Rotate keys regularly. Create a new key, update your integration, then revoke the old one.
• Use minimal scopes. A widget integration only needs chat — don't grant actions unless required.

Dual Authentication

The API gateway supports both methods simultaneously:

Method	Header	Use Case
API Key	Authorization: Bearer sk_live_xxx	Server-to-server, widgets, SDK
JWT Cookie	Cookie: Senda-Token=xxx	Senda SPA (internal)

If both are present, the API key takes precedence.