LobeHub API Authentication, Workspaces, and Scopes
Every /api/v1 request except GET /api/v1/health, /api/v1/openapi.json, and /api/v1/docs must carry a bearer token:
Authorization: Bearer <token>The server decides what kind of token it is by its shape:
- A token in the API key format (
sk-lh-plus 16 lowercase letters and digits) is looked up as an API key. The key must be enabled and not expired. - Any other token is validated as an OIDC access token (an RS256 JWT for the audience
urn:lobehub:chat), signed by the deployment's OIDC provider. Self-hosted instances accept OIDC tokens only whenJWKS_KEYis configured.
There is no X-API-Key header. A missing or invalid token returns 401.
Choose a Credential
| You are building | Use |
|---|---|
| A server-side integration, script, or CI job acting as yourself | An API key with the narrowest scopes that work |
| A native or desktop app where each user signs in | OIDC authorization code with PKCE, with a public client the deployment provides (see OIDC with PKCE) |
| A third-party web app that users authorize | An OAuth app registered in Settings: client secret plus PKCE (see below) |
| A command-line tool on a device without a browser | The OIDC device flow (used by the built-in lobehub-cli client) |
API Keys
Create keys in Settings → API Keys of a Workspace (/<workspace>/settings/apikey). A key belongs to the person who created it and to that Workspace.
- What a key can do is the intersection of its creator's own permissions (Workspace role and RBAC) and the key's scopes. Scopes only narrow access; they never grant more than the creator has.
- The creator can change a key's scopes later on its detail page (Edit permissions). Workspace admins can revoke other members' keys but cannot change their scopes.
- A key created before scopes existed, or created with Full access, has every scope.
OIDC with PKCE
LobeHub runs an OpenID Connect provider at <origin>/oidc.
| Endpoint | Path |
|---|---|
| Discovery | /oidc/.well-known/openid-configuration |
| Authorization | /oidc/auth |
| Token | /oidc/token |
| User info | /oidc/me |
| JWKS | /oidc/jwks |
| Device authorization | /oidc/device/auth |
| Revocation | /oidc/token/revocation |
PKCE is required for every authorization code request. Use code_challenge_method=S256.
Which client you can use:
- LobeHub's own apps use built-in public clients (
lobehub-desktop,lobehub-mobile, and others). A public client has no secret, so the token request below sends onlyclient_id. - Your own app on LobeHub Cloud registers a web OAuth app in Settings (see OAuth Apps). It is a confidential client: add
client_secretto the token request, and use anhttpsor loopbackhttpredirect URI. Custom URL schemes such asmyapp://are not accepted for self-registered apps today. - Public clients for third-party native apps become possible with dynamic client registration (
token_endpoint_auth_method: none), which is coming soon in #23322.
Authorization Code Flow
-
Create a random
code_verifierand its S256code_challenge(base64url of the SHA-256 digest). -
Open the authorization URL in the system browser:
Plaintextresource=urn:lobehub:chatasks for an access token that/api/v1accepts.offline_accesswithprompt=consentreturns a refresh token. -
After sign-in, LobeHub redirects to
redirect_uriwithcodeandstate. Reject the callback ifstatedoes not match. -
Exchange the code:
Shell -
Call the API with
Authorization: Bearer <access_token>. Refresh withgrant_type=refresh_tokenbefore it expires.
Refresh tokens rotate: every refresh returns a new refresh token and the old one stops working, so always store the latest. Refresh tokens and sessions last 30 days.
The TypeScript SDK implements these steps as createPkcePair, createAuthorizationUrl, parseAuthorizationCallback, exchangeAuthorizationCode, and refreshAccessToken for public clients; they do not send a client secret. See SDKs.
OAuth Apps
To let other people authorize your application, register it in Settings → OAuth Apps (/<workspace>/settings/oauth-apps):
- A web app gets a client id
lca_…and a client secretlcs_…, shown once. It uses theauthorization_codeandrefresh_tokengrants withclient_secret_post. - A device app is a public client that uses the device flow.
- Redirect URIs must use
https, orhttpon a loopback address. Wildcards are not allowed, and an app can have at most 20.
Today an OAuth access token is a full user token: it reaches the same API as its user, without scope narrowing.
Coming soon (#23322): fine-grained API scopes
for OAuth tokens (the same names as API key scopes, shown on the consent page), dynamic client
registration at POST /oidc/reg with a single-use registration token, and the
client_credentials grant for server-to-server apps. Each is turned on per deployment with an
environment variable.
Workspace Selection
Requests run in either the caller's personal space or one Workspace. The Workspace is resolved from the credential and the optional X-Workspace-Id header:
| Credential | X-Workspace-Id | Result |
|---|---|---|
| Workspace API key | Not sent | Runs in the key's Workspace |
| Workspace API key | Same Workspace | Runs in the key's Workspace |
| Workspace API key | Different Workspace | 403 Workspace API Key cannot access a different workspace |
| Personal API key | Sent | 403 Personal API Key cannot access workspace data |
| OIDC token | Sent | Runs in that Workspace if the user is a member, otherwise 403 Not a member of this workspace |
| OIDC token | Unknown Workspace id | 404 Workspace not found |
| Workspace API key | Its Workspace does not allow API keys | 403 Workspace API Key access is not available |
Inside a Workspace, some operations also need a minimum Workspace role (viewer < member < admin < owner). A request below it returns 403 Requires <role> role or higher.
Scopes
Scopes are defined in packages/const/src/apiKeyScope.ts. A :write scope also grants the matching :read scope.
Available Scopes
| Scope | Grants |
|---|---|
* | Full access: everything the creator can do, except the explicit-only scopes listed below once they ship |
agent:read / agent:write | Agents, Agent groups, tasks, goals, plugins, skills |
agent:credential:write | Setting a password, token, or signing key on an Agent account (needs agent:write as well) |
chat:read / chat:write | Topics, messages, threads, sessions, translations |
model:invoke | Calling models: POST /responses, chat, image, video, speech, transcription. This is the scope that spends credits |
model:read / model:write | Providers and model configuration |
file:read / file:write | Files, uploads, parsing, and chunks |
knowledge:read / knowledge:write | Libraries (knowledge bases), documents, chunks |
mcp:read / mcp:write | MCP server configuration |
eval:read / eval:write | Evaluations, Benchmarks, Datasets, Test Cases |
usage:read | Usage and credit quota |
workspace:read / workspace:write | Workspace details, members, audit log |
user:read / user:write | The user profile, settings, Memory, notifications |
Some operations need several scopes. For example POST /responses needs model:invoke, chat:write, and agent:write, because it runs an Agent and writes the conversation.
Restricted keys can never reach API key management, roles and RBAC administration, or billing, whatever scopes they hold.
A scope check failure returns 403. Once unified error codes ship, the code is insufficient_scope; see Errors.
Coming Soon Scopes
These scopes are added by open pull requests together with the endpoints that need them:
| Scope | Endpoints | Pull request |
|---|---|---|
run:read / run:write | /runs (Agent runs, events, cancel, steer, approvals) | #23253 |
webhook:read / webhook:write | /webhooks | #23272 |
document:read / document:write | /documents, /notebooks | #23255 |
generation:read / generation:write | /images, /videos, /generations, /audio | #23267 |
tool:invoke | POST /tools/call | #23274 |
agent:transfer | Moving an Agent to another Workspace or member | #23292 |
share:read / share:write | Public share links | #23301 |
project:read / project:write, widget:read / widget:write / widget:publish, dashboard:read / dashboard:write, artifact:publish | /projects, /widgets, /dashboards, artifact publishing | #23311 |
oauth_app:read / oauth_app:write, trash:read / trash:write | /oauth-apps, /trash | #23315 |
device:read / device:operate | /devices, sandboxes | #23316 |
bot:read / bot:write | /bots | #23332 |
device:operate is planned as an explicit scope: full access does not include it, and it must be ticked by name when the key is created.
After #23246 ships, each operation in the OpenAPI spec lists the scopes it needs under x-required-scopes, and the SDK shows them in each method's documentation.