It's standard OAuth 2: the authorization code flow with PKCE. Every address below is also in the discovery document, https://app.reviewflowz.com/.well-known/oauth-authorization-server.
1. Register your app
Send your app's name, where to send people back, and the permissions it will ask for (the same ones a key has):
curl https://app.reviewflowz.com/oauth/register \-H "Content-Type: application/json" \-d '{"client_name": "Acme CRM","redirect_uris": ["https://acme.example/reviewflowz/callback"],"scope": "sources:read reviews:read"}'
{"client_id": "kT3vX0c1hJ8mR5wQ2nB7yL4dF9sA6gZ1","client_name": "Acme CRM","redirect_uris": ["https://acme.example/reviewflowz/callback"],"grant_types": ["authorization_code", "refresh_token"],"response_types": ["code"],"token_endpoint_auth_method": "client_secret_basic","client_secret": "..."}
Keep the client_secret: it's shown this once. Redirect addresses must be https.
An app that can't keep a secret, like a mobile or single-page app, sends "token_endpoint_auth_method": "none" and gets no secret.
2. Ask for access
Send the person to the authorize address, with a state of your own and a PKCE challenge (the SHA-256 of a random code_verifier you keep, base64url-encoded):
https://app.reviewflowz.com/oauth/authorize?response_type=code&client_id=kT3vX0c1hJ8mR5wQ2nB7yL4dF9sA6gZ1&redirect_uri=https://acme.example/reviewflowz/callback&scope=sources:read+reviews:read&state=af0ifjsldkj&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
They sign in, pick the account to connect when they have several, and allow the permissions. We send them back to your redirect_uri with a code and your state. The code is good for 10 minutes.
3. Get a token
Exchange the code, with the code_verifier from step 2:
curl https://app.reviewflowz.com/oauth/token \-u "CLIENT_ID:CLIENT_SECRET" \-d grant_type=authorization_code \-d code=CODE \-d redirect_uri=https://acme.example/reviewflowz/callback \-d code_verifier=CODE_VERIFIER
{"access_token": "...","token_type": "Bearer","expires_in": 7776000,"refresh_token": "...","scope": "sources:read reviews:read","created_at": 1794229936}
4. Call the API
Send the access token like a key: Authorization: Bearer <access_token>. It acts as the person who allowed it, on the account they picked, with the permissions they allowed. GET /v3/account says which account that is.
5. Keep it working
An access token lasts 90 days. Before it runs out, trade the refresh token for a new pair, and keep both:
curl https://app.reviewflowz.com/oauth/token \-u "CLIENT_ID:CLIENT_SECRET" \-d grant_type=refresh_token \-d refresh_token=REFRESH_TOKEN
When someone disconnects your app, revoke their token:
curl https://app.reviewflowz.com/oauth/revoke \-u "CLIENT_ID:CLIENT_SECRET" \-d token=ACCESS_TOKEN