Authentication

Overview

Authentication is required for all BSOS API requests. Your API key identifies the partner application making the request and determines which workspaces it can access.

API keys should be stored securely on your backend. They should never be exposed in client-side code, public repositories, browser scripts, or mobile applications.

Authorization Header

Include your API key in the Authorization header using the Bearer format.

Authorization: Bearer YOUR_API_KEY

Example Request

POST /api/v1/signals/analyze
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "workspace_id": "workspace_123",
  "source": "email",
  "subject": "Contract renewal question",
  "body": "Can you confirm the renewal terms before Friday?"
}

Workspace Access

Every request must belong to a workspace. BSOS uses the workspace context to keep customer data, users, signals, and decisions logically separated.

If an API key does not have access to the requested workspace, the API returns an authorization error.

Common Authentication Errors

Error Response Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key."
  }
}

Security Recommendations

• Keep API keys only on your backend.
• Do not expose API keys in frontend code.
• Rotate keys if you suspect they were leaked.
• Use separate keys for production and development environments.
• Send only the workspace data required for the operation.