Docs / API and agents
Session and shell API
How the web app learns who is calling, the shell data per workspace, and the public apply context.
The session is an Auth.js-compatible encrypted cookie issued by services. Every route needs a valid session unless it is marked public (default-deny, auth/session.guard.ts). A bearer token carrying the same value is accepted for the mobile shell.
How a session is checked#
- Decode the token with the shared secret; reject an expired or clock-invalid one (24 hour session).
- Reject it when the user logged out, when the user's sessions were revoked after it was issued, or when its organization is revoked (suspended or denied tenants).
- Apply the workspace and impersonation overlays. They can only narrow or re-target a verified session, never create one.
- Anything else is a 401. State-changing browser requests also pass the Origin guard: a foreign
Originheader is a 403; clients that send none (mobile, curl) pass.
Routes#
| Method and path | Who | What |
|---|---|---|
GET /session | session (401 when signed out) | { user, impersonating } |
GET /session/post-login?next= | session | where to go next: /onboarding for a new customer without an organization, a safe same-site next, or the role's landing page |
GET /shell/vendor, /shell/applicant, /shell/platform | session | header and navigation data for each workspace (counts of pending references, unread messages) |
GET /account/workspaces, GET /account/vendor-start | session | which workspaces the business has enabled |
GET /apply/context | public; a session adds prefill and history | what the apply page needs for a supplier link or QR |
POST /reference/:token/vendor-start, POST /reference/saved/:token/vendor-start | public | start a supplier signup from a reference page: sets a short-lived cookie and redirects (303) to /signup?as=vendor&from=reference |
POST /auth/sign-out | public (ends dead sessions too) | clears the session cookies |
POST /auth/heartbeat | session | renews the cookie while the user is active |
All session-dependent answers carry Cache-Control: private, no-store.