Authentication - Basics Gateway API

Use the auth model that fits your integration. Most teams start with a Basics API key. If you want provider-level control, use BYOK on the supported routes.

Public API authentication

For customer-facing endpoints, send a Basics API key in the Authorization header:

curl https://api.basicsos.com/v1/models \
  -H "Authorization: Bearer bos_live_sk_..."

Use this auth model for:

/v1/chat/completions
/v1/messages
/v1/embeddings
/v1/connections
/v1/execute/...
/v1/audio/transcriptions
/v1/audio/speech
/v1/email/send

GET /health and GET /v1/models are public and do not require authentication.

User-scoped requests

Some gateway routes can also be scoped to a specific signed-in user.

Connections endpoints use X-User-Id: <user_id>
Execute endpoints accept X-User-Id and or userId in the request body
If both are present on execute endpoints, userId in the body wins
If both are omitted, the gateway falls back to the legacy org-wide connection

See /api-reference/connections-and-execute for the endpoint details.

BYOK headers

Some public endpoints also support BYOK, or bring your own key. With BYOK, you send a provider API key directly to the gateway so requests run against your provider account. Supported providers are:

openai
anthropic
gemini
deepgram

Send these headers with your request:

Header	Required	Description
`x-byok-provider`	Yes	Provider name: `openai`, `anthropic`, `gemini`, or `deepgram`
`x-byok-api-key`	Yes	Your provider API key
`x-byok-api-base`	No	Custom base URL, such as Azure OpenAI
`x-byok-api-version`	No	Provider API version when required

BYOK example

curl https://api.basicsos.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-byok-provider: anthropic" \
  -H "x-byok-api-key: $ANTHROPIC_API_KEY" \
  -d '{
    "model": "basics-chat-smart",
    "messages": [
      { "role": "user", "content": "Write a short greeting." }
    ]
  }'

BYOK support by endpoint

Use the matrix below to see where BYOK is supported:

/v1/chat/completions: Basics key or BYOK with OpenAI, Anthropic, or Gemini
/v1/messages: Basics key or BYOK with OpenAI, Anthropic, or Gemini
/v1/embeddings: Basics key or BYOK with OpenAI or Gemini
/v1/audio/transcriptions: Basics key or BYOK with Deepgram
/v1/audio/speech: Basics key or BYOK with Deepgram
/v1/email/send: Basics key only

Authentication failures

If your token or API key is missing or invalid on a protected route, the gateway returns the shared error format documented on /api-reference/errors.

​Public API authentication

​User-scoped requests

​BYOK headers

​BYOK example

​BYOK support by endpoint

​Authentication failures