Skip to Content
SaaSFlow
Developers

OAuth for apps

Build a third-party app that other SaaSFlow companies can install — OAuth 2.1 + PKCE.

If you're building an integration that other SaaSFlow companies install on their own account (not your own scripts), use the OAuth flow. SaaSFlow is the authorization server; your app is the client.

At a glance

  • Flow: OAuth 2.1 Authorization Code + PKCE.
  • Authorization server: https://api.saasflow.com/auth
  • Scopes: see the table below.
  • Token type: JWT bearer.

Scopes

ScopeGrants
saasflow:readRead access to the company's data.
saasflow:writeWrite access (still bounded by the granting user's permissions).
saasflow:adminCompany settings and integration management (company:manage, integrations:manage), still bounded by the granting user's permissions. The user ticks it separately on the consent screen.
saasflow:create_companiesPOST /companies: create companies with the user as owner. Ticking it on the consent screen accepts the Terms of Service and the Data Processing Agreement on behalf of each company your app creates. API keys cannot create companies.
openid, profile, emailIdentity claims via the userinfo endpoint.
offline_accessA refresh token, for access beyond the first hour.

Request only what you need. A data-only integration typically asks for saasflow:read offline_access; the official CLI requests the six default scopes.

Register your app

OAuth client registration is currently a manual step — email support@saasflow.com with:

  • App name
  • Redirect URI(s)
  • Logo (optional, shown on the consent screen)
  • Requested scopes

You'll receive a client_id to use in the flow below.

The flow

Generate PKCE pair

import { randomBytes, createHash } from 'crypto';

function base64url(buf: Buffer) {
    return buf.toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
}

const verifier = base64url(randomBytes(32));
const challenge = base64url(createHash('sha256').update(verifier).digest());
const state = base64url(randomBytes(16));

Redirect to the authorize endpoint

https://api.saasflow.com/auth/oauth2/authorize?
    response_type=code
  & client_id=YOUR_CLIENT_ID
  & redirect_uri=https%3A%2F%2Fyour-app.com%2Foauth%2Fcallback
  & scope=saasflow%3Aread%20saasflow%3Awrite
  & state=STATE
  & code_challenge=CHALLENGE
  & code_challenge_method=S256

The user signs in at app.saasflow.com (if not already), picks which company to grant access to, and approves the scopes.

Handle the callback

SaaSFlow redirects to your redirect_uri with code and state. Verify state matches what you sent.

Exchange code for token

POST https://api.saasflow.com/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=THE_CODE
&redirect_uri=https://your-app.com/oauth/callback
&client_id=YOUR_CLIENT_ID
&code_verifier=THE_VERIFIER

Response:

{
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "scope": "saasflow:read saasflow:write",
    "expires_in": 3600,
    "refresh_token": "..."
}

Call the API

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

Refresh

When expires_in runs out, POST the same /auth/oauth2/token endpoint with grant_type=refresh_token and the stored refresh_token.

Permission scoping

A token's effective permissions are the intersection of:

  • The granted scopes (saasflow:read, saasflow:write, saasflow:admin).
  • The granting user's current permissions in the company.
  • Live revocation status (we re-check the consent grant on every request).

Of the *:manage permissions, only company:manage and integrations:manage can be granted via OAuth, through saasflow:admin. Managing members and API keys is never available to an OAuth app.

userinfo

GET https://api.saasflow.com/auth/oauth2/userinfo
Authorization: Bearer eyJ...

Returns { sub, email, name } for the user that granted consent.

Revocation

Users can revoke your app from Settings → API keys in the SaaSFlow app. The next request with that token returns 401.

On this page