Authentication

Boost.space authenticates every request with an HTTP Bearer token in the Authorization header. The base URL is per-tenant: pass system (→ https://{system}.boost.space/api) or a full baseUrl/base_url.

1. Static API token

Created in the user profile; authorizes requests as that user.

bs = BoostSpace("api-token", system="acme")

const bs = new BoostSpace({ token: "api-token", system: "acme" });

$bs = new BoostSpace('api-token', system: 'acme');

bs := boostspace.NewClient("api-token", boostspace.WithSystem("acme"))

2. Token provider (resolved per request)

token also accepts a callable that is called before each request — so a short-lived token is always current:

bs = BoostSpace(lambda: current_access_token(), system="acme")   # sync or async

new BoostSpace({ token: () => currentAccessToken(), system: "acme" });

new BoostSpace(fn () => currentAccessToken(), system: 'acme');

boostspace.NewClient("", boostspace.WithSystem("acme"),
    boostspace.WithTokenProvider(func(ctx context.Context) (string, error) { return current(ctx) }))

3. OAuth2 (and MCP tokens)

The API exposes a full OAuth2 flow: GET /auth/oauth/authorize → POST /auth/oauth/token (grant_type=authorization_code then refresh_token) → a short-lived access_token + refresh_token + expires_in, plus revoke and token-info.

> MCP tokens are ordinary OAuth2 access tokens. An MCP client is just an > OAuth2 client registered with mcp=true (dynamic client registration); there > is no separate token type or header — the same flow and the same > OAuth2Session apply.

OAuth2Session runs the flow and refreshes proactively (60 s before expiry), and is itself a token provider:

from boostspace.runtime import OAuth2Session
session = OAuth2Session("client-id", "client-secret", system="acme",
                        refresh_token=stored)          # or: session.exchange_code(code, redirect_uri=...)
bs = BoostSpace(session, system="acme")                # token kept fresh

const session = new OAuth2Session({ clientId, clientSecret, system: "acme", refreshToken: stored });
const bs = new BoostSpace({ token: session.provider(), system: "acme" });

$session = new OAuth2Session('client-id', 'client-secret', system: 'acme', refreshToken: $stored);
$bs = new BoostSpace($session->provider(), system: 'acme');

session := boostspace.NewOAuth2Session("client-id", "client-secret",
    boostspace.OAuth2WithSystem("acme"), boostspace.OAuth2WithRefreshToken(stored))
bs := boostspace.NewClient("", boostspace.WithSystem("acme"),
    boostspace.WithTokenProvider(session.Provider()))

OAuth2Session exposes exchangeCode/exchange_code, refresh, and token(), plus the current accessToken/refreshToken/expiresAt so you can persist and restore them.

Overview

Delta sync & bulk operations