Authentication

Brainstormer uses JWT (JSON Web Token) bearer authentication for all API requests. Tokens are obtained via the login or register endpoints and must be included in every subsequent request.

How It Works

Authenticate via POST /api/auth/login or POST /api/auth/register to obtain an access token and refresh token.
Include the access token in the Authorization header of every API request.
When the access token expires (24 hours), use the refresh token to obtain a new pair via POST /api/auth/refresh.

All API requests go through the API Gateway on port 4000, which decodes the JWT and forwards user context to backend services.

Optional verified identity on public endpoints

Public distribution endpoints (e.g. GET /api/public/agents/:slug) can optionally accept a bearer token. When present, the gateway verifies the JWT signature and forwards verified user-id and organization-id headers to the bot service so that group-restricted agents can evaluate membership. When the token is absent, public endpoints behave exactly as before and serve only agents that do not require membership or group access.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

Token Format

The JWT payload contains:

string

Unique user identifier (UUID).

string

User’s email address.

string

Platform-level role: user or superadmin.

array

List of organizations the user belongs to.

Show Organization object

string

Organization UUID.

string

Organization display name.

string

URL-friendly organization slug.

string

User’s role in this org: owner, admin, editor, or viewer.

number

Token issued-at timestamp (Unix seconds).

number

Token expiration timestamp (Unix seconds).

Token Lifetimes

Token	Default Lifetime
Access token	24 hours
Refresh token	7 days

Header Format

Include the access token as a Bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The API Gateway also accepts the token from an access_token cookie as a fallback, but the Authorization header is the primary method.

Developer portal showing API key management — The Developer portal for managing API keys and authentication

Obtaining Tokens

Register

Create a new user account and receive tokens.

curl -X POST https://your-domain.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123",
    "displayName": "Jane Doe",
    "organizationName": "My Workspace"
  }'

const response = await fetch("https://your-domain.com/api/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    password: "securepassword123",
    displayName: "Jane Doe",
    organizationName: "My Workspace",
  }),
});

const { data } = await response.json();
const { accessToken, refreshToken, user } = data;

Response (201):

{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "displayName": "Jane Doe",
      "emailVerified": false,
      "accountType": "standard",
      "platformRole": "user",
      "isSuperAdmin": false,
      "status": "active",
      "organizations": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "name": "My Workspace",
          "slug": "my-workspace",
          "role": "owner"
        }
      ]
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Authenticate with email and password.

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'

const response = await fetch("https://your-domain.com/api/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    password: "securepassword123",
  }),
});

const { data } = await response.json();
// data.accessToken, data.refreshToken, data.user

Response (200): Same shape as the register response.

Refreshing Tokens

When the access token expires, exchange the refresh token for a new pair.

curl -X POST https://your-domain.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'

const response = await fetch("https://your-domain.com/api/auth/refresh", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    refreshToken: storedRefreshToken,
  }),
});

const { data } = await response.json();
// Store new data.accessToken and data.refreshToken

Response (200):

{
  "success": true,
  "data": {
    "user": { ... },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Error Responses

Status	Error	When
400	Validation Error	Missing or invalid fields in request body
401	Authentication Failed	Wrong email/password, expired token, or missing `Authorization` header
401	Missing or invalid authorization header	No Bearer token provided

The API Gateway cryptographically verifies the JWT signature (HMAC-SHA256) on every request. Downstream services trust the gateway-forwarded identity headers and must never be exposed directly to the internet.

Organization Context

The JWT contains all organizations the user belongs to. The first organization in the array is the active organization for all API requests. All data in Brainstormer is scoped to an organization. When you create agents, knowledge bases, or other resources, they are automatically associated with your active organization.

Switching the active organization

POST /api/auth/switch-org with { "organizationId": "<uuid>" } and a valid access token re-issues a new access + refresh token pair with the chosen organization placed first, so every subsequent request scopes to it. The caller must be a member of the target organization (otherwise 403), a suspended account is refused, and a refresh token is rejected. Persist the returned tokens exactly as you do after login — both of them: the choice is carried on the refresh token, so discarding it and reusing an older one puts the session back in the default organization. When a platform administrator has configured Google OAuth (Client ID + Secret in Admin → System Config), users can sign in or sign up with Google.

GET /api/auth/google begins the OAuth 2.0 authorization-code flow (with state and PKCE) and redirects the browser to Google’s consent screen.
GET /api/auth/google/callback receives Google’s code, exchanges it server-side, verifies the returned ID token (signature, audience, issuer), then signs the user in and redirects back to the app with the issued tokens in the URL fragment.

If the Google account’s email matches an existing Brainstormer account, the two are linked automatically — but only when Google reports the email as verified. Accounts created through Google have no password until the user sets one via Forgot password, which adds email-and-password sign-in alongside Google. These endpoints are unauthenticated (the user is signing in) and are not called directly by API clients; they are top-level browser navigations.

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Authentication

Authentication

How It Works

Optional verified identity on public endpoints

Token Format

Token Lifetimes

Header Format

Obtaining Tokens

Register

Refreshing Tokens

Error Responses

Organization Context

Switching the active organization

​Authentication

​How It Works

​Optional verified identity on public endpoints

​Token Format

​Token Lifetimes

​Header Format

​Obtaining Tokens

​Register

​Login

​Refreshing Tokens

​Error Responses

​Organization Context

​Switching the active organization

​Sign in with Google

Authentication

How It Works

Optional verified identity on public endpoints

Token Format

Token Lifetimes

Header Format

Obtaining Tokens

Register

Login

Refreshing Tokens

Error Responses

Organization Context

Switching the active organization

Sign in with Google