Authentication & endpoints

This page covers accounts, environments and API keys. Your application calls its environment with an environment API key. The console and the account API use your browser session.

The two planes

Plane	Host	Auth	You use it to…
Data plane (lbb-server)	Environment-specific endpoint_url	Bearer environment API key	Write records, search, run SPARQL, manage graphs
API	api.littlebigbrain.com	Browser session cookie	Manage accounts, environments, and keys

Applications almost always call the data plane with an environment API key. The hosted console uses the account API for sign-in and environment management.

Creating an account

Sign in or sign up in the hosted console. After you sign up, little big brain creates your personal workspace. You are its administrator.

To finish signup, review the monthly plan and select Subscribe. Then add a card on Stripe’s hosted page. The first monthly minimum is charged at once. On the Cloud plan, this is €19 including applicable VAT, or $21 plus applicable tax.

Your workspace opens after payment succeeds. Then you can create environments and use the platform. If you cancel payment setup, signup stays pending and you can try again. Renewals fall monthly on your signup date. Account settings and sign-out stay available throughout.

Existing workspaces keep their access. An organization invitation adds you to that account, with the role it assigns. You use the account’s subscription, so each member needs no plan of their own.

Invite people

Owners and admins invite people from Settings. Select Invite people there or in the account menu. Enter one or more email addresses and choose a role:

• Member uses the account’s environments and changes nothing.
• Admin also manages members, environments, keys and the organization.

Each person gets an email with a link to join. The pending invitations list under the members. You can resend or revoke each one.

Environments

An environment is an isolated tenant. It has its own graphs, data and keys. Create environments in the console (Environments view) or with the account API.

Each environment has a slug, such as product-dev. MCP URLs and admin calls use it. A slug is unique in one account, and another account can use the same slug.

Environment API keys

An environment API key is a bearer credential. It looks like this:

lbb_sk_live_XXXXXXXXXXXXXXXXXXXX     # production environment
lbb_sk_test_XXXXXXXXXXXXXXXXXXXX     # test environment

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

curl "$LBB_URL/v1/graph/summary?graph=main" \
  -H "Authorization: Bearer $LBB_API_KEY"

The SDKs take the key when you create the client:

const lbb = new LbbClient({ baseUrl: process.env.LBB_URL!, apiKey: process.env.LBB_API_KEY });

lbb = LbbClient(os.environ["LBB_URL"], api_key=os.environ["LBB_API_KEY"])

Each new environment starts with an initial key. An environment can have up to 10 active keys. Create one named key per service, machine or environment. You can then revoke each integration on its own.

Each key can be revoked, including the initial key and the last active key. A environment with no active keys refuses environment-key authentication.

Manage keys on the console’s Access keys page. A secret is shown once, when you create it. The information icon beside the page title explains how to store and revoke keys. The key list reads the selected environment’s keys directly, so it loads without delay.

Keep keys server-side

A lbb_sk_live_… key can read and write its whole environment. Keep it in server environment variables or a secret manager. Never ship it in a browser bundle or commit it. The console does not store raw API keys.

If a key leaks, create a replacement, and update and check the integration. Then revoke the old key. If containment matters more than uptime, revoke it first. For agents, use 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.

Compatible names

Older APIs and integrations call an environment a stack. Existing management routes such as /api/stacks, response fields such as stack_id, the X-LBB-Stack MCP header, API key prefixes and DNS names retain their wire spelling. The console calls these resources environments. This terminology change does not move data, change key permissions or create a new tenant identity.

Optional scoped read tokens are separate from environment API keys and hosted MCP OAuth. See How to model your app for their read-only contract and deployment requirements.

Base URLs

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

Purpose	URL
Hosted environment 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-hosted distribution is planned. It will serve one fixed tenant and graph, with a token you set.

Selecting a graph

An environment has a default graph, usually main. To use another, pass the graph query parameter. In the SDKs, set the client’s graph option or call client.graph("name"):

curl "$LBB_URL/sparql?graph=support" \
  -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 uses OAuth 2.1. An MCP client with remote auth, such as Claude or Cursor, finds the flow by itself. It receives an authorization challenge, runs the browser sign-in and sends an access token.

The server checks the token and confirms that your account owns the environment. Then it opens a short-lived session to the environment. Your machine never holds a little big brain key. The MCP guide has the details.

Discover the issuer and endpoints

The MCP protected-resource metadata publishes resource: "https://mcp.littlebigbrain.com" and its authorization_servers array. Use the advertised issuer to fetch its /.well-known/oauth-authorization-server or /.well-known/openid-configuration. The issuer’s JSON provides authorization_endpoint, token_endpoint, jwks_uri, grant_types_supported and response_types_supported.

Agents starting at the homepage can also follow the OAuth discovery, OIDC discovery and protected-resource discovery aliases. They redirect to current metadata from AuthKit or the hosted MCP service. Validate the issuer and resource at their canonical metadata URLs. Use the MCP origin as the OAuth resource and token audience; your environment is selected by the MCP URL or X-LBB-Stack header. The marketing origin is only an entry point for discovery. Environment HTTP APIs and developer integrations use the API keys described above and in the integrations guide.

Auth.md agent registration

Read auth.md for the current registration instructions. While WorkOS Agent Registration is disabled, it describes the existing human OAuth flow. When the issuer advertises agent_auth, the site serves WorkOS’s generated claim and credential instructions with the MCP resource and environment-selection guidance.

A claimed agent needs the trusted mcp:access permission. It grants read and write access through MCP to environments owned by the delegated user’s organization. Every request checks the credential’s signature, issuer, expiration and MCP audience, then confirms current provider validity, a completed service-auth claim, organization binding and the user’s active membership. A cached internal database session cannot bypass these checks. Anonymous or unclaimed agents and provider agent API keys are refused; missing permission returns 403 insufficient_scope.

The agent permission is separate from the standard identity scopes used by human OAuth clients. Dynamically registered clients should request only the issuer’s supported identity scopes. Revoke an agent in WorkOS Authentication → Agents → Registrations. After revocation the next MCP request is refused.

Error responses

Every non-2xx response has a JSON body of the form {"error": {...}}. The object holds type, code, message, param, request_id and doc_url. A retryable error also has retryable: true and retry_after_seconds.

The SDKs raise the error as LbbError, with the HTTP status and the same values. Use code in your code, for example for a 404 on a missing graph. Responses and errors lists the codes.

Two errors come from the environment endpoint. 421 stack_endpoint_required means the host is missing or malformed. 403 stack_endpoint_mismatch means the key belongs to another environment. In both cases, copy endpoint_url from the console.