WeBot API docs

Authentication

The implemented API accepts public catalog reads, authenticated Supabase session requests, and bearer API keys for account routes.

Supported methods

Public

GET /api/v1/catalog and GET /api/v1/openapi.json do not require auth.

Supabase session

Dashboard-owned requests start from account sign-in and resolve an active account membership and role before returning data. Cookie-authenticated dashboard mutations also carry CSRF verification.

Open account access

WeBot API key

API callers send a bearer key for catalog, jobs, files, usage, and account reads. Bearer keys do not create or revoke other API keys.

Bearer key request

curl https://api.webot.agency/api/v1/me \
  -H "Authorization: Bearer $WEBOT_API_KEY" \
  -H "X-Request-Id: req_docs_auth_example"

API key management

Owners and admins with a dashboard session from /login can list key metadata, create a key, and revoke a key. The dashboard is the normal management surface. Cookie-authenticated create and revoke requests also send x-webot-csrf-token. The create route returns plaintext_key once; list and revoke responses return metadata only. Treat that one-time value as sensitive: store it in a credential manager, never log it, and never include real keys in screenshots.

curl https://api.webot.agency/api/v1/api-keys \
  -H "Cookie: sb-access-token=$SUPABASE_ACCESS_TOKEN"

curl https://api.webot.agency/api/v1/api-keys \
  -X POST \
  -H "Cookie: sb-access-token=$SUPABASE_ACCESS_TOKEN" \
  -H "x-webot-csrf-token: $WEBOT_DASHBOARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production automation" }'

curl https://api.webot.agency/api/v1/api-keys/key_example \
  -X DELETE \
  -H "Cookie: sb-access-token=$SUPABASE_ACCESS_TOKEN" \
  -H "x-webot-csrf-token: $WEBOT_DASHBOARD_CSRF"

Dashboard session refresh

Sign-in stores Supabase access and refresh tokens in HTTP-only, same-site cookies. If a dashboard page finds the access token expired, the auth-required panel can post to /auth/refresh with a relativenext path. The route exchanges only the existing refresh cookie, resets session cookies, and refuses external redirect targets.

curl https://app.webot.studio/auth/refresh \
  -X POST \
  -H "Cookie: sb-refresh-token=$SUPABASE_REFRESH_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "next=/dashboard"

Environment boundaries

Staging and production reject test-only auth toggles. Account access comes from Supabase sessions or WeBot API keys, and paid access comes only from signed Stripe webhook state.

Deployed environments fail closed when required auth, CSRF, Stripe, Supabase, or server-side operations secrets are missing or placeholder values. Keep local test helpers out of staging and production configuration.

Access safety

The API resolves account, role, scopes, and entitlements on the server. Signed Stripe webhook state is the source of paid access; checkout query parameters never grant access, quota, or dashboard permissions.

Safe auth failures

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required.",
    "request_id": "req_example"
  }
}