Authentication

API Key Authentication

The simplest way to authenticate is with an API key. Include your key in the Authorization header as a Bearer token on every request.

API keys are ideal for server-to-server communication where you control the environment and can keep the key secure. Never expose API keys in client-side code, browser applications, or public repositories.

curl -X POST https://api.bolor.ai/v1/orchestrai/route \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello, world!"}'

import requests

headers = {
    "Authorization": "Bearer sk-your-api-key",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.bolor.ai/v1/orchestrai/route",
    headers=headers,
    json={"query": "Hello, world!"}
)

print(response.json())

const response = await fetch(
  "https://api.bolor.ai/v1/orchestrai/route",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk-your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "Hello, world!" }),
  }
);

const data = await response.json();
console.log(data);

JWT Token Authentication

For applications that need short-lived, user-scoped tokens, Bolor Intelligence supports JWT-based authentication. This is the recommended approach for web and mobile applications where you need to authenticate on behalf of individual users.

JWT tokens are obtained by authenticating with your account credentials and have a configurable expiration time (default: 1 hour). Each token is scoped to the permissions of the authenticated user.

Obtaining a Token

curl -X POST https://api.bolor.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
  "email": "user@example.com",
  "password": "your-password"
}'

# Response:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIs...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "refresh_token": "rt_xxxxxxxxxxxxxxxx"
# }

Using the Token

curl -X POST https://api.bolor.ai/v1/orchestrai/route \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello, world!"}'

OAuth2 Password Flow

For programmatic access from trusted backend services, Bolor Intelligence supports the OAuth2 Resource Owner Password Credentials flow. This flow exchanges user credentials directly for an access token without browser-based authorization.

This flow should only be used in server-side applications where you can securely handle user credentials. Never use this flow in client-side applications.

curl -X POST https://api.bolor.ai/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username=user@example.com" \
  -d "password=your-password" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "scope=orchestrai mindvault"

import requests

token_response = requests.post(
    "https://api.bolor.ai/v1/oauth/token",
    data={
        "grant_type": "password",
        "username": "user@example.com",
        "password": "your-password",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "scope": "orchestrai mindvault",
    }
)

access_token = token_response.json()["access_token"]

# Use the token for subsequent requests
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.post(
    "https://api.bolor.ai/v1/orchestrai/route",
    headers=headers,
    json={"query": "Hello, world!"}
)

Token Refresh

Access tokens expire after the configured TTL (default: 1 hour). When a token expires, use the refresh token to obtain a new access token without re-authenticating.

Refresh tokens have a longer lifespan (default: 30 days) and can only be used once. Each refresh request returns a new refresh token along with the new access token.

curl -X POST https://api.bolor.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
  "refresh_token": "rt_xxxxxxxxxxxxxxxx"
}'

# Response:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIs...(new)",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "refresh_token": "rt_yyyyyyyyyyyyyyyy(new)"
# }

Authentication Errors

When authentication fails, the API returns a standard error response with an HTTP 401 status code.