Authentication

Every public API call must authenticate. SaaSFlow accepts three credential types and picks them up in this order:

1. Authorization: Bearer sf_… — API key
2. Authorization: Bearer <jwt> — OAuth bearer
3. Cookie: saasflow-…=… — session cookie

Session cookie

Used by the SaaSFlow web app and by any code that runs in a browser on .saasflow.com. Issued by Better Auth at sign-in, scoped to .saasflow.com so every subdomain (app.saasflow.com, docs.saasflow.com, …) sees the same session.

Don't try to hand-roll this from a server — use an API key or OAuth instead.

API keys

Long-lived secrets you create in the dashboard. Format:

sf_<36-char-id><36-char-secret>

Best for scripts, CI, server-to-server integrations, and the CLI. Keys carry a custom permission set; you can create read-only keys, write keys, etc.

Send them as a bearer token:

curl https://api.saasflow.com/companies \
  -H "Authorization: Bearer sf_..."

Manage keys at Settings → Company settings → API keys. Full instructions at API keys.

OAuth bearer

OAuth 2.1 + PKCE flow, issued by Better Auth's OAuth provider. Best for:

• The CLI's default browser login.
• Hosted MCP clients (Claude, ChatGPT).
• Third-party apps that users install on their own company.

Tokens are JWTs with one of two scopes: saasflow:read (read-only) or saasflow:write (reads + writes). The effective permissions of a token are the intersection of the scope and the granting user's permissions.

Send them as a bearer token:

curl https://api.saasflow.com/companies \
  -H "Authorization: Bearer eyJhbGciOi..."

The OAuth endpoints are at https://api.saasflow.com/auth/*. See OAuth for apps for the flow details.

Which one should I use?