Access control
Surplus uses passwordless authentication — no passwords to store or leak. Users prove identity with a one-time email code; a short-lived signed access token, renewed with a refresh token, keeps them signed in. Authorization is enforced on the server on every request.
Sign-in flow
- Request a code — user enters email; a six-digit code is generated, stored briefly in Redis, and emailed. The endpoint returns the same response whether or not the email exists (enumeration resistance).
- Validate the code — on success, the app's auth endpoints set two HttpOnly cookies: a 15-minute access token and a 90-day refresh token.
- Stay signed in — requests carry the access token automatically. A few minutes before it expires, the app asks the auth endpoints for a new one, which also replaces the refresh token.
- Sign out — ends the session on the server, so the refresh token stops working everywhere, and clears both cookies.
Rate limiting (auth)
- Code requests: 5 / 15 minutes per email + IP
- Code validation: 10 / 15 minutes per email
- OAuth authorization requests: 30 / minute per IP
- OAuth token and revocation requests: 60 / minute per IP
Rate limiting (server calls)
- Global traffic: 100 / 10 seconds per client IP (the address Cloudflare reports)
- Signed-in admins and advisors: 300 / 10 seconds per user instead, since their dashboards make many calls and staff share office IPs
Rate limiting (MCP)
MCP's limits are sliding windows in Redis, shared by every instance of the app, on top of the global limit above:
- Per client IP: 60 / 10 seconds on every MCP route
- Per user: 30 / minute for authenticated MCP requests (tool calls and the rest of the protocol)
Tokens
The app's auth endpoints (/auth) are the only part of Surplus that issues tokens. Every sign-in, in the web app or an MCP client, gets the same pair of JWTs:
- Access token: lasts 15 minutes and is sent with every request. The app API, stored files, and MCP verify it with the app's public key, by signature alone
- Refresh token: accepted only by the auth endpoints, and replaced on every use. Web app refresh tokens last 90 days and MCP client ones 30 days, counted from the last renewal
- Algorithm: ES256. Only the auth endpoints sign with the private key
- Payload: the user's id, issuer, audience, and expiry — no roles or scopes embedded
Each sign-in's chain of refresh tokens is tracked on the server. If an already-replaced refresh token is ever used again, it was copied, so the whole chain is ended and the user signs in again. Signing out ends the chain the same way.
Permissions are loaded fresh from the database on each request, so suspending or changing access takes effect immediately, and a suspended user can't renew their tokens.
Cookies
- HttpOnly — not readable by JavaScript
- Secure — HTTPS only in staging and production
- SameSite=Lax — mitigates CSRF
- Scoped — both are host-only cookies for the app's own host; the refresh token is sent only to the auth endpoints (
/auth) - Environment-scoped — separate names and domains per environment so staging and production sessions never collide
Invalid or missing tokens return 401; suspended accounts return 403.
Roles
| Role | Access |
|---|---|
admin | Full administrative access |
advisor | Read-oriented oversight (users, cost-sharing, tags) |
partner | Scoped to linked donor/recipient organizations |
driver | Assigned routes, stops, and their events |
| suspended | null permission — blocked from all protected endpoints |
Authorization layers:
- One gatekeeper — every API call has an access rule, checked before it runs: it rejects unauthenticated and suspended users, and checks the role's permission for that action.
- Resource checks — the same check compares the records a call names with the user's organizations and assigned routes, so partners only reach organizations they're linked to and drivers only their routes. A call the gatekeeper can't decide is refused.
- File access — files are served by the app at
/filesafter a check, never as public bucket URLs. A file's URL is given only in responses the user may already read. Logos, covers, gallery photos and avatars open for any signed-in user. Attachments and generated documents (collection events, distribution events, routes) need a signed link, which the app gives only to users who may read the record, and which expires within 20 minutes. Images on the public impact map are signed links that expire within three days.
Attachments carry an internal or external visibility flag — partners see external attachments only.
Terms acceptance
Users must accept the current Terms of Use and Privacy Policy before using the app. Bumping the version re-prompts everyone.
MCP OAuth
Remote MCP clients use a separate OAuth 2.1 path — not the web session cookie. Only admin and advisor accounts may call MCP tools.
For connector setup, environments, tools, and resources, see MCP integration.
Related
- App API — how the web app's server calls are authenticated
- Data protection — how session data is handled in logs
