OAuth 2.1

OAuth lets your app act on behalf of a Zoop user — reading their customers, creating jobs, or sending invoices — without ever seeing their password. The user approves access through a consent screen; you get a short-lived access token (a credential your app includes on every API request) and a refresh token (used to get a new access token when the first one expires).

Use OAuth when your app serves multiple Zoop accounts or when you need access tied to a specific user's identity. If you are building a server-to-server integration that runs unattended and does not need a user identity, API keys are simpler.

How it works

Zoop uses OAuth 2.1 with PKCE (Proof Key for Code Exchange — a security extension that stops attackers from hijacking the authorization code in transit). The auth server is Supabase — Zoop owns the consent screen and the grant table, but the actual token exchange happens against the Supabase auth endpoint.

The access token is a JWT (JSON Web Token) — a signed string that encodes the user's identity, tenant, and allowed scopes. Zoop verifies it on every request without a database lookup. The signature algorithm is ES256.

Your app              Supabase auth             Zoop
   |                       |                      |
   |-- GET /authorize -->   |                      |
   |                       |-- 302 → consent -->  |
   |                       |                      |
   |   (user approves)     |                      |
   |                       |                      |
   |-- POST /token ------> |                      |
   |                       |                      |
   |<-- access_token + refresh_token -------------|
   |                                              |
   |-- POST /api/mcp (Bearer <access_token>) ---> |

Prerequisites

Before you run this flow, you need an OAuth client and a redirect URI.

1. An OAuth client. Public clients — ChatGPT, Claude, MCP connectors, native apps, SPAs — self-register against the Supabase auth server using RFC 7591 Dynamic Client Registration. No Zoop admin is involved. You discover the registration_endpoint from the authorization server metadata (see Discovery) and POST your client details to it; you get back a client_id. See Self-serve client registration below. Confidential (server-side) clients that need a client_secret can still be registered by a Zoop admin.

2. A redirect URI. The URL in your app where Zoop sends the user after they approve access. You register it with the client — unregistered URIs are rejected.

A freshly registered client holds no access until a user completes the consent flow (default-deny). What that user can grant is bounded by their ceiling, not by the client alone — see Scopes below.

Discovery

Before you build any URLs, find out which authorization server your Zoop instance uses. Do not hardcode it — resolve it from the protected-resource metadata endpoint:

GET https://app.zoop.pro/.well-known/oauth-protected-resource

Response:

{
  "resource": "https://app.zoop.pro",
  "authorization_servers": ["https://<project>.supabase.co/auth/v1"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://docs.zoop.pro/api"
}

The authorization_servers array tells you which Supabase project handles auth for this instance. Use that URL to fetch the authorization server metadata — this gives you the exact authorization_endpoint and token_endpoint you will need in the steps below:

GET https://<project>.supabase.co/auth/v1/.well-known/oauth-authorization-server

This endpoint returns standard OAuth 2.0 server metadata: supported grants, PKCE methods, scopes, and the registration_endpoint you use for self-serve client registration.

Self-serve client registration

Public MCP clients register themselves — there is no Zoop admin step. Fetch the authorization server metadata (see Discovery), read its registration_endpoint, and POST your client metadata there following RFC 7591 Dynamic Client Registration. You get back a client_id (and, for confidential clients, a client_secret). Registration runs against the Supabase auth server, not the Zoop app.

A self-registered client starts with no allow-list and no access. At consent it is offered the connecting member's whole ceiling to choose from — there is no fixed read-only default scope set. See Scopes.

The authorization flow

import { randomBytes, createHash } from 'crypto'

const codeVerifier = randomBytes(64).toString('base64url')
const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url')
const state = randomBytes(32).toString('base64url')

// Store both in the user's session — you need them in the callback.
session.codeVerifier = codeVerifier
session.oauthState = state

GET https://<project>.supabase.co/auth/v1/oauth/authorize
  ?client_id=<your_client_id>
  &redirect_uri=<your_registered_redirect_uri>
  &response_type=code
  &code_challenge=<codeChallenge>
  &code_challenge_method=S256
  &state=<state>
  &scope=openid
  &resource=https://app.zoop.pro

https://app.zoop.pro/oauth/consent?authorization_id=<opaque_id>

https://your-app.example.com/callback?code=<authorization_code>&state=<your_state>

const { code, state } = new URL(request.url).searchParams

if (state !== session.oauthState) {
  throw new Error('State mismatch — possible CSRF attack')
}

// Safe to proceed.

curl -X POST https://<project>.supabase.co/auth/v1/oauth/token \
  -H "Authorization: Basic $(echo -n '<client_id>:<client_secret>' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=<authorization_code>" \
  --data-urlencode "redirect_uri=<your_registered_redirect_uri>" \
  --data-urlencode "code_verifier=<codeVerifier>" \
  --data-urlencode "resource=https://app.zoop.pro"

curl -X POST https://<project>.supabase.co/auth/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=<your_client_id>" \
  --data-urlencode "code=<authorization_code>" \
  --data-urlencode "redirect_uri=<your_registered_redirect_uri>" \
  --data-urlencode "code_verifier=<codeVerifier>" \
  --data-urlencode "resource=https://app.zoop.pro"

{
  "access_token": "<es256-signed-jwt>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<opaque-refresh-token>"
}

curl -X POST https://app.zoop.pro/api/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

const res = await fetch('https://app.zoop.pro/api/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'customers_search',
      arguments: { q: 'Henderson' },
    },
  }),
})

The access token

The access token is a JWT signed with ES256. If you want to inspect what's inside — for example, to check which tenant or scopes were granted — paste it into jwt.io. Zoop validates these claims on every request.

{
  "iss": "https://<project>.supabase.co/auth/v1",
  "sub": "<user_uuid>",
  "tenant_id": "<tenant_uuid>",
  "scopes": ["read:customers", "read:jobs"],
  "client_id": "<your_client_id>",
  "role": "owner"
}

Refreshing tokens

Access tokens expire after one hour. When that happens, use the refresh token to get a new one — no browser redirect needed.

curl -X POST https://<project>.supabase.co/auth/v1/oauth/token \
  -H "Authorization: Basic $(echo -n '<client_id>:<client_secret>' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=<refresh_token>" \
  --data-urlencode "resource=https://app.zoop.pro"

curl -X POST https://<project>.supabase.co/auth/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=<your_client_id>" \
  --data-urlencode "refresh_token=<refresh_token>" \
  --data-urlencode "resource=https://app.zoop.pro"

A successful response has the same shape as the original token response — a new access_token and expires_in, and sometimes a new refresh_token. If you get a new refresh token, store it and discard the old one.

If the refresh request returns 401 with error: "invalid_token", the user's session has been terminated (for example, they signed out). You need to send them through the full authorization flow again.

Scopes

What your app can read or write is decided at consent, not by the scope parameter in the authorization request (that parameter only carries OIDC scopes like openid). The scopes a user can grant are bounded by the connecting member's ceiling ∩ your client's allow-list:

• A fresh self-registered client has no allow-list, so it is offered the member's whole ceiling to choose from.
• A client that pre-registered scopes is narrowed down to the member's ceiling — anything outside the ceiling is dropped.
• If the member's ceiling is empty, nothing is offered and the grant gives no access.

There is no fixed read-only default scope set for self-registered clients anymore. Granted scopes are re-checked against the member's current ceiling on every request, so if an owner lowers that member's ceiling later, the token narrows immediately. See scopes & permissions for the ceiling model and the permission areas shown on the consent screen.

Common scope sets to request:

Request only the scopes your integration actually needs. See scopes for the full catalog.

Error reference

These are the errors you are most likely to see from the API after you have a token.

Retry 5xx responses with exponential backoff. Do not discard your token on a 5xx — it may be valid and the error transient.

Related

• API keys — simpler M2M authentication without a browser flow
• Scopes — full scope catalog
• MCP — calling the MCP endpoint with your access token
• Errors — full error code reference
• Rate limits — per-credential and per-tenant limits