API authentication, scopes and roles
Create scoped API keys, sign in from a browser with a passphrase and CSRF token, understand owner, editor and viewer roles, and connect remote MCP clients with OAuth 2.1.
There are two ways in, and they never interfere with each other.
| API key | Browser session | |
|---|---|---|
| For | Scripts, integrations, MCP, AI assistants | The web app |
| Credential | Authorization: Bearer glideworth_<prefix>_<secret> |
Passphrase sign-in, then an httpOnly cookie |
| Scopes | Per key: read, simulate, write |
The user’s role |
| Writes need | Nothing extra | An X-CSRF-Token header |
/mcp |
Yes | No (MCP is bearer-only) |
API keys
Keys are stored as a SHA-256 hash only. The secret is shown once, at creation, and is never logged.
| Scope | Allows |
|---|---|
read |
GET everything, and run compute (simulations, solvers, insights). |
simulate |
Run compute and read job status and results, but not read raw data (a “calculator” key). |
write |
All mutations: plans, finances, change sets, keys, webhooks and imports. Implies read and simulate. |
A key can only mint keys with scopes it has itself, and never has more than its user’s role allows. The last active
write key cannot be revoked.
Create a key in the app under Settings, then API keys, or from the command line:
pnpm keys:create -- --name laptop --scopes read,simulate
On Docker: docker compose exec glideworth node dist/cli/create-key.js --name laptop --scopes read.
On first boot, if there are no keys and GLIDEWORTH_BOOTSTRAP_KEY is set, it is inserted with read and write scope. The
public example key in .env.example is refused in production.
Browser sign-in
In production the browser signs in with a passphrase you choose on first run. These routes are public, under
/api/v1/auth:
| Route | Purpose |
|---|---|
GET /api/v1/auth/status |
Whether setup is required, whether you are authenticated, your user, and a CSRF token. |
POST /api/v1/auth/setup |
First run only: set the passphrase (12 or more characters) and sign in. With GLIDEWORTH_SETUP_TOKEN set, the token must be sent too. |
POST /api/v1/auth/login |
Open a session. Omit the sign-in name for the owner. |
POST /api/v1/auth/accept |
Accept an invite or a passphrase reset with a token and a new passphrase. |
POST /api/v1/auth/change-passphrase |
Change your own. Your other sessions are signed out. |
POST /api/v1/auth/logout, /api/v1/auth/logout-all |
End this session, or all of your sessions. |
The passphrase is hashed with scrypt and compared in constant time. The session cookie is a random 256-bit token,
HttpOnly and SameSite=Strict, stored server-side only as a hash. A session lasts 168 hours at most
(GLIDEWORTH_SESSION_TTL_HOURS) with a 24-hour idle timeout (GLIDEWORTH_SESSION_IDLE_HOURS). Cookie-authenticated
writes must send X-CSRF-Token, and an Origin header, if sent, must match the server. API-key requests are exempt.
Failed sign-ins are throttled per client and globally (GLIDEWORTH_LOGIN_MAX_ATTEMPTS in
GLIDEWORTH_LOGIN_WINDOW_MINUTES, default 5 in 15), and the 429 applies even to the right passphrase until the window
passes. Behind a reverse proxy set GLIDEWORTH_TRUST_PROXY=true so the real client address is used.
Roles
| Role | Can |
|---|---|
owner |
Everything, including users, webhooks, OAuth clients and the audit log. |
editor |
Read, simulate and write; not users, webhooks or the audit log. |
viewer |
Read and simulate only. |
A role caps every credential of that person. A viewer’s POST /plans is 403 FORBIDDEN with details
{ "required": "write", "role": "viewer" }. Related routes: GET /me, GET/POST /me/keys, DELETE /me/keys/{id}, GET /users, POST /users (invite), POST /users/{id}/invite, PATCH /users/{id}, DELETE /users/{id},
POST /users/{id}/reset-passphrase and GET /audit-log.
OAuth for remote MCP clients
Hosted MCP clients that connect by URL sign in with OAuth 2.1 following the MCP authorisation specification: discovery at
/.well-known/oauth-protected-resource, dynamic client registration at POST /oauth/register, a consent screen at
/oauth/authorize, and PKCE (S256 only) at POST /oauth/token. Tokens last an hour and refresh with rotation. OAuth
tokens are accepted on /mcp only. Scopes are the same three, capped by the role of the user who consents. Set
GLIDEWORTH_PUBLIC_URL behind a proxy. Manage grants with GET/DELETE /me/oauth-grants (yours) or
GET/DELETE /oauth/clients (owner).
Last checked against the code on .