# Authentication & endpoints

Source: https://docs.littlebigbrain.com/start/authentication/

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](https://cloud.littlebigbrain.com) uses the account API for
sign-in and environment management.

## Creating an account

Sign in or sign up in the [hosted console](https://cloud.littlebigbrain.com).
After you sign up, little big brain creates your personal workspace. You are
its administrator.

To finish signup, review the [monthly plan](https://docs.littlebigbrain.com/start/billing/) 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.

<span id="stacks"></span>

## 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.

<span id="stack-api-keys"></span>

## 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:

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

The SDKs take the key when you create the client:

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

```python
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.

:::caution[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](#hosted-mcp-oauth), 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](https://docs.littlebigbrain.com/start/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](https://docs.littlebigbrain.com/start/endpoints/) 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")`:

```sh
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](https://docs.littlebigbrain.com/sdks/mcp/) has the details.

### Discover the issuer and endpoints

The [MCP protected-resource metadata](https://mcp.littlebigbrain.com/.well-known/oauth-protected-resource)
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](https://littlebigbrain.com/.well-known/oauth-authorization-server),
[OIDC discovery](https://littlebigbrain.com/.well-known/openid-configuration) and
[protected-resource discovery](https://littlebigbrain.com/.well-known/oauth-protected-resource)
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](https://docs.littlebigbrain.com/guides/integrations-for-your-customers/).

### Auth.md agent registration

Read [auth.md](https://littlebigbrain.com/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](https://docs.littlebigbrain.com/sdks/http-api/#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.