Authentication
The API is built for browsers. You log in with Google or GitHub, the API sets a session cookie, and every call sends that cookie. There are no API keys yet.
TODO: decide whether server-to-server clients get API keys, and document them here.
Logging in
Section titled “Logging in”Login is OAuth with Google or GitHub (authorization code with state and PKCE). The endpoints under
/api/auth/ are served by Better Auth; the ones a client needs:
| Call | What it does |
|---|---|
POST /api/auth/sign-in/social with { "provider": "google" | "github", "callbackURL": "/" } |
Answers { "url": "..." }: send the browser there |
GET /api/auth/callback/{provider} |
The provider sends the browser back here; the API sets the session cookie and redirects to callbackURL |
POST /api/auth/organization/set-active with { "organizationId": "..." } |
Switches the active workspace |
POST /api/auth/sign-out |
Ends the session |
Start the login from the browser that will use the session: the first call also sets a short-lived cookie that the callback checks.
Rules:
- Only an email address that Google or GitHub has verified gets an account. A Google and a GitHub account with the same verified address are one user.
- When a login fails, the browser is sent to
/login?error=<code>on the app, for examplestate_mismatch,account_not_linked,email_not_verifiedorlogin_failed. - The endpoints under
/api/auth/answer errors in Better Auth’s own shape,{ "code", "message" }, not the API’s error shape.
The session cookie
Section titled “The session cookie”| Name | __Secure-better-auth.session_token (on plain http in local development: better-auth.session_token) |
| Attributes | HttpOnly, Secure, SameSite=Lax |
| Lifetime | 8 hours; while you use it, the expiry moves forward (at most once every 30 minutes) |
From a browser on another origin (for example the web app on app. calling api.), send credentials
(fetch(url, { credentials: 'include' })). Only origins the API trusts get CORS access, and the only request
header they may set is Content-Type.
Without a valid session, every endpoint under /v1/ answers 401 with code unauthenticated.
The Origin header
Section titled “The Origin header”Every request other than GET must carry an Origin header naming a trusted origin: the API’s own origin or
the web app’s. Browsers send it themselves. With curl, add it:
--header 'Origin: https://api.dev.loupestack.com'A missing or other origin gets 403 with code csrf_check_failed. This is on top of the cookie’s
SameSite=Lax, so that another site cannot make a logged-in browser change anything.
Workspaces and roles
Section titled “Workspaces and roles”A workspace holds the data sources, descriptions, questions and dashboards of one team or company. A user can
belong to several; each session has one active workspace (the first one, until you switch), and every
/v1/ call acts on it. You never send a workspace id in a request.
Each membership has a role:
| Role | Can |
|---|---|
member |
Read the workspace’s sources, saved queries, descriptions, sync jobs and UIs; ask questions; chat; generate and change UIs; delete their own UIs |
admin |
Everything a member can, plus: add, change and remove connectors, table descriptions and sync jobs; delete anyone’s UI |
owner |
The same as admin |
Memberships are read on every request, so someone who is removed loses access at once. Workspaces and their first owner are created by the Loupestack team; more members are added by email address and become active at their next login.
TODO: document inviting members once owners can do it through the API.
How the reference shows who may call what
Section titled “How the reference shows who may call what”Each operation in the reference lists the cookie under “Authentication”, with role names:
| Role names on the operation | Who may call it | Otherwise |
|---|---|---|
| none | Anyone who is logged in, with or without a workspace (only GET /v1/me) |
401 unauthenticated |
member |
Any member of the active workspace | 403 no_workspace |
owner, admin |
Owners and admins of the active workspace | 403 admin_required |
These come from the same declaration that the API enforces, so the reference cannot say something the API does not do. One operation adds its own rule: a UI can be deleted by the member who created it, and by owners and admins.