Build an integration that acts on your users' StitchDB organizations with OAuth 2.1: register a client, ask for organization scopes, provision projects.
An integration (a hosting platform, a CMS, a developer tool) can ask a StitchDB user to connect one of their organizations, then create and manage projects there with the user's consent. It is standard OAuth 2.1 with PKCE; the access tokens act like an organization token with the scopes the user approved.
#1. Register your app
Register once, as a confidential client, and keep the secret on your server:
curl -X POST https://stitchdb.com/platform/oauth/register \
-H 'Content-Type: application/json' \
-d '{ "client_name": "Acme Deploy", "redirect_uris": ["https://acme.example/stitchdb/callback"],
"token_endpoint_auth_method": "client_secret_post", "client_uri": "https://acme.example" }'The answer has client_id and client_secret (shown once). The name is what users see on the consent screen. Discovery: https://stitchdb.com/.well-known/oauth-authorization-server.
#2. Send the user to authorize
https://stitchdb.com/platform/oauth/authorize?response_type=code
&client_id=sdb_client_…&redirect_uri=https://acme.example/stitchdb/callback
&scope=projects:write database:write functions:write
&code_challenge=<S256 of your verifier>&code_challenge_method=S256&state=<random>When the scope has organization scopes, the user picks one organization where they are an owner or administrator and sees the exact list of what your app may do. Only an owner can grant billing:read. They come back to your redirect_uri with code and state.
| Scope | Lets the app |
|---|---|
projects:read | List and read projects (always included) |
projects:write | Create, change, pause, restore and delete projects; rotate keys; read service_role keys and database passwords |
database:read / database:write | Read-only SQL, types, dumps / SQL writes and migrations |
functions:write / secrets:write | Deploy Edge Functions / set their secrets |
auth:write | Change Auth settings |
usage:read | Usage and metering |
webhooks:write | Manage the organization's webhooks |
billing:read | Plan, limits and billing state (owner only) |
Ask for the fewest scopes you need. mcp:read / mcp:write alone (no organization scope) is the per-person AI tool consent instead (see AI tools).
#3. Exchange the code
curl -X POST https://stitchdb.com/platform/oauth/token \
-d grant_type=authorization_code -d code=sdb_oac_… -d code_verifier=<verifier> \
-d redirect_uri=https://acme.example/stitchdb/callback -d client_id=sdb_client_… -d client_secret=sdb_cs_…You get an access_token (1 hour) and a refresh_token (30 days, rotated on every use; a reused one ends the connection). scope lists what was granted.
#4. Call the API
curl https://stitchdb.com/platform/v1/organizations -H "Authorization: Bearer $ACCESS_TOKEN"
# [{ "id": "<org>", "name": "…", "role": "admin", "via": "org_token" }]
curl -X POST https://stitchdb.com/platform/v1/projects -H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' -d '{ "name": "acme-site-42", "organization_id": "<org>" }'Everything in the Platforms API and Management API works within the granted scopes, including short-lived project tokens for one project. The app can never create organization tokens, list or disconnect apps, or reach another organization.
#Disconnecting
- Any owner or administrator of the organization: Organization › API tokens › Connected apps › Disconnect (or
DELETE /platform/v1/organizations/<org>/apps/<id>). - The person who connected it: Account › Access tokens › Authorized apps.
- Automatically, when the person who connected it is no longer an owner or administrator of the organization.
- Your app:
POST /platform/oauth/revokewith the refresh token.
Afterwards the access and refresh tokens, and any project tokens the app made, stop working within seconds. Connecting and disconnecting show up in the organization's activity log.