Skip to content
Not publicly available.This describes the Loupestack API before launch. Endpoints, limits and fields can still change.

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.

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 example state_mismatch, account_not_linked, email_not_verified or login_failed.
  • The endpoints under /api/auth/ answer errors in Better Auth’s own shape, { "code", "message" }, not the API’s error shape.
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.

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:

Terminal window
--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.

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.

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.