Authentication & endpoints

little big brain has two planes, and you authenticate to each differently.

The two planes

Plane	Host	Auth	You use it to…
Data plane (lbb-server)	Stack-specific endpoint_url	Bearer stack API key	Load RDF, run SPARQL, manage graphs and branches
API	api.littlebigbrain.com	Browser session cookie	Manage accounts, stacks, and keys

Applications almost always talk to the data plane with a stack API key. The hosted console uses the account API for sign-in and stack management.

Stacks

A stack is an isolated workspace with its own graphs, its own data, and its own keys. You create stacks from the console (Stacks view) or the account API. Each stack has an account-scoped slug such as product-dev, used in MCP URLs and admin calls. The same slug can exist in another account.

Stack API keys

A stack API key is a bearer credential that looks like:

lbb_sk_live_XXXXXXXXXXXXXXXXXXXX     # production stack
lbb_sk_test_XXXXXXXXXXXXXXXXXXXX     # test stack

Pass it as a bearer token on every data-plane request:

curl https://0abc1def--production.db.eu.littlebigbrain.com/v1/graph/summary?graph=main \
  -H "Authorization: Bearer $LBB_API_KEY"

The SDKs take the key at construction:

const lbb = new LbbClient({ baseUrl: "https://0abc1def--production.db.eu.littlebigbrain.com", apiKey: process.env.LBB_API_KEY });

lbb = LbbClient("https://0abc1def--production.db.eu.littlebigbrain.com", api_key=os.environ["LBB_API_KEY"])

Each new stack starts with an initial key and supports up to 10 active keys. Create one named key per service, machine, or environment so each integration can be revoked independently. Every key is revocable, including the initial and final active key; a stack with no active keys rejects stack-key authentication. Manage them from the console Keys & access page, where every secret is shown only once, when created.

Keep keys server-side

A lbb_sk_live_… key grants full read/write to its stack. Keep it in server environment variables or a secret manager, and never ship it in browser bundles or commit it. The console does not persist raw API keys. If a key leaks, create a replacement, update and verify the integration, then revoke the old key. If immediate containment matters more than uptime, revoke it first. For agents, prefer the hosted MCP OAuth flow so the key never leaves the server.

Where to store it

• Node / server: process.env.LBB_API_KEY.
• Python: os.environ["LBB_API_KEY"].
• MCP (local): the LBB_API_KEY env var in your editor’s MCP config.
• CI / deploys: your secret store.

Base URLs

Applications must use the complete tenant-plus-stack endpoint copied from the console, https://<tenant-short-id>--<stack-slug>.db.eu.littlebigbrain.com. See Endpoints & base URLs for the addressing model.

Purpose	URL
Hosted stack example	https://0abc1def--production.db.eu.littlebigbrain.com
API	https://api.littlebigbrain.com
Hosted MCP endpoint	https://mcp.littlebigbrain.com
Console	https://cloud.littlebigbrain.com
Marketing site	https://littlebigbrain.com

A self-hostable distribution is planned. It will run in a single-tenant mode (one fixed tenant, graph, and branch) authenticated with a token you set.

Selecting a graph and branch

A stack has a default graph and branch, usually main. To target another, pass query parameters. The SDKs expose the same through client.graph("name") and options:

curl "https://0abc1def--production.db.eu.littlebigbrain.com/sparql?graph=support&branch=candidate" \
  -H "Authorization: Bearer $LBB_API_KEY" \
  -H "Accept: application/sparql-results+json" \
  --data-urlencode 'query=SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5'

Hosted MCP OAuth

The hosted MCP endpoint at mcp.littlebigbrain.com authenticates with OAuth. It is an OAuth 2.1 protected resource: an MCP client that supports remote auth (Claude, Cursor) discovers the flow from an authorization challenge, runs the browser sign-in, and presents an access token. The server validates the token, confirms your account owns the stack, and issues a short-lived data-plane session, so your machine never holds a little big brain key. Full details in the MCP guide.

Error responses

Every non-2xx response is a structured JSON error that the SDKs raise as a typed exception (LbbError). The response field set is status, type, code, message, param, requestId, and docUrl; use code for programmatic handling of common cases such as a 404 on a missing graph. Two errors come from the addressing model: 421 stack_endpoint_required means the host is missing or malformed, and 403 stack_endpoint_mismatch means the credential belongs to a different stack. In either case, copy endpoint_url from the console.