Partner OAuth
Partner OAuth is the browser half of a partner app install. GET /v1/oauth/authorize sends a merchant to Flint's consent screen to approve the permissions your app requests, then returns them to your app with an authorization code. Your backend exchanges that code for an install token at the token endpoint.
GET /v1/oauth/authorize/preview checks the same inputs and returns, as JSON, the app and permissions the consent screen will show. Use it to validate an install link before you send a merchant to it, or to show the request in your own product.
Neither endpoint takes an API key. Register the app, its redirect URIs, and its permission manifest first with the Partner apps routes.
How an install moves#
- Your server redirects the merchant's browser to
GET /v1/oauth/authorizewith astateand a PKCE challenge. - Flint shows the consent screen. The merchant signs in, chooses a merchant, and chooses Install app or Deny.
- Flint redirects the browser to your
redirect_uriwithcode,state, andmode, or with anerror. - Your backend sends the code and its
code_verifiertoPOST /v1/oauth/tokenand receives an access token, a refresh token, and the install IDs.
Each install has a separate grant, with its own tokens, for each mode. Authorize mode=test and mode=live separately. A live install needs a merchant that has finished onboarding.
Build the authorize URL#
These rules span several parameters:
stateand the PKCE pair belong together. For each install attempt, generate a randomstateand acode_verifierof 43 to 128 URL-safe characters, and store them together. Sendcode_challenge, the unpadded base64url SHA-256 hash of the verifier, which is always 43 characters.code_challenge_methodmust beS256;plainisn't supported.redirect_urimust match exactly. It must equal one of the app's registered redirect URIs, character for character. Send the same value again on the token request.scopelists permission IDs, not API scopes. Use IDs from your app's permission manifest, separated by spaces. Omitscopeto request the app'sdefault_requested_permissions. Flint always adds the manifest's required permissions, the ones withoutoptional: true.sandbox_idworks only withmode=test. It picks the sandbox the test grant uses. Without it, Flint uses the merchant's default sandbox.merchant_idis a hint. It preselects a merchant on the consent screen when the person can access several.- Each parameter can appear once. Flint ignores parameters it doesn't recognize.
With Node.js:
import { createHash, randomBytes } from "node:crypto";
const state = randomBytes(16).toString("base64url");
const codeVerifier = randomBytes(32).toString("base64url");
const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
// Store codeVerifier with state for this attempt.
const authorizeUrl = new URL("https://api.withflintpay.com/v1/oauth/authorize");
authorizeUrl.search = new URLSearchParams({
response_type: "code",
client_id: process.env.FLINT_CLIENT_ID,
redirect_uri: "https://acme.example.com/flint/oauth/callback",
mode: "test",
state,
scope: "manage_orders read_customers",
code_challenge: codeChallenge,
code_challenge_method: "S256",
}).toString();
// Redirect the merchant's browser to authorizeUrl.
Responses on the callback#
When the merchant chooses Install app, Flint redirects to your redirect_uri with code, state, and mode. Flint keeps any query string the registered URI already has and adds these parameters to it.
https://acme.example.com/flint/oauth/callback?code=fpac_abc123&mode=test&state=8tQ2mZxv1pL0aR7c
Check that state matches a value you issued and load its code_verifier, then exchange code right away. A code expires after 5 minutes, works once, and is replaced when the merchant authorizes the same mode again.
Where errors go#
Flint redirects an error to your app only after it has matched client_id to an active app and redirect_uri to one of its registered URIs. The error redirect carries error, error_description, and your state.
| Problem | What Flint does |
|---|---|
client_id matches no active app, redirect_uri is missing or unregistered, or either appears more than once. | Returns a Flint error envelope to the browser. No redirect. |
| Another parameter is wrong. | Redirects with error. |
A problem the merchant can fix, such as signing in, identity verification, admin access, onboarding for a live install, or a sandbox_id from another merchant. | Keeps the merchant on the consent screen, where they can fix it or choose Deny. |
| The merchant chooses Deny. | Redirects with error=access_denied. |
The redirected error values are:
error | Cause |
|---|---|
access_denied | The merchant chose Deny. |
invalid_request | state is missing, mode isn't test or live, sandbox_id was sent with mode=live, code_challenge is missing or malformed, code_challenge_method isn't S256, or a parameter is repeated. |
invalid_scope | scope is empty or names a permission that isn't in your manifest. |
unsupported_response_type | response_type isn't code. |
server_error | Flint couldn't complete the request. Send the merchant again later. |
error_description is fixed text for people. Branch on error.
Preview an install request#
Call the preview with the same query parameters as the authorize URL:
curl "https://api.withflintpay.com/v1/oauth/authorize/preview?client_id=FPC_CLIENT_ID&redirect_uri=https%3A%2F%2Facme.example.com%2Fflint%2Foauth%2Fcallback&mode=test&scope=manage_orders%20read_customers"
The preview differs from the authorize URL in a few ways:
- Only
client_id,redirect_uri, andmodeare required. Flint validatesresponse_type,state,code_challenge, andcode_challenge_methodwhen you send them, and ignoresmerchant_id. - It never redirects. Every problem comes back as a Flint error envelope, such as
400 INVALID_REQUESTwithparamsandbox_idfor asandbox_idsent withmode=live. - It doesn't know the merchant yet, so it doesn't check sandbox ownership or onboarding. The consent screen does.
requested_permissions is the exact set the consent screen will request, sorted by permission_id, including required permissions you didn't list. Each entry carries the title and description from your manifest and the Flint API scopes it grants in required_scopes. requested_permission_ids lists the same IDs.
partner_app_version is the app's current version. The merchant's approval is tied to the version the consent screen showed: if you change the app while a merchant is on the screen, Install app fails and Flint shows them the updated request. Ship manifest changes before you send merchants to consent.
Deleting an app archives it. The authorize URL and the preview then treat its client_id as unknown.
Exchange the code#
Exchange the code at POST /v1/oauth/token with grant_type=authorization_code, the code, the code_verifier, and the same redirect_uri. The request authenticates as your app with one of these:
| Method | Send |
|---|---|
| Self-signed client assertion | client_assertion: a new JWT for each request, signed by the key of a public_key or jwks_url credential. |
| Workload identity assertion | client_assertion: a token from the issuer of a workload_identity credential. It can be reused until it expires. |
| Client secret | HTTP Basic, or client_id and client_secret form fields, for apps with client_secret_enabled. |
Both assertion methods also send client_id, and client_assertion_type set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Never combine an assertion with a client secret or HTTP Basic. Client assertions authenticate partner apps only, not flint-cli. The token endpoint reference lists the claim rules. For worked examples, see how to sign a client assertion and exchange the code, then refresh and revoke tokens, in Partner app installs.
Authorize partner install#
/v1/oauth/authorizeNo API key required
Rate limit: per IP
Starts a partner app install in the merchant's browser. Flint validates the request, then redirects to Flint's consent screen, where the merchant signs in, chooses a merchant, and approves or denies the requested permissions. Flint then redirects to redirect_uri with code, state, and mode, or with an OAuth error. Request errors found before consent also redirect with an OAuth error once client_id and redirect_uri are validated. Unknown or inactive clients and missing or unregistered redirect URIs return the Flint error envelope. This route takes no credential, and Flint ignores any Authorization header. Flint ignores unrecognized parameters.
Query parameters
response_typeenumRequiredOAuth response type. Must be code.
code
client_idstringRequiredPartner app client ID.
redirect_uristringRequiredRegistered redirect URI for the partner app.
modeenumRequiredInstall mode.
testlive
code_challengestringRequiredBase64url-encoded SHA-256 hash of your code_verifier, without padding (RFC 7636).
code_challenge_methodenumRequiredPKCE challenge method.
S256
scopestringSpace-separated permission IDs from your app's permission manifest. Omit to request default_requested_permissions. Required permissions are always granted.
sandbox_idstringOptional active merchant sandbox ID, accepted only with mode=test. When omitted in test mode, Flint uses the merchant's default sandbox.
merchant_idstringOptional merchant to preselect on the consent screen when the person can access several merchants.
statestringRequiredOpaque state value returned to the partner callback.
Response · 302
Redirect to Flint's consent screen, or to the partner callback with an OAuth error. Error values before consent are unsupported_response_type, invalid_request, invalid_scope, and server_error. After the merchant decides, Flint redirects to redirect_uri with the code, state, and mode query parameters when they approve, or with an OAuth error when they deny.
curl "https://api.withflintpay.com/v1/oauth/authorize?response_type=code&client_id=fpc_00112233445566778899aabbccddeeff&redirect_uri=example&mode=test&code_challenge=example&code_challenge_method=S256&state=example" \
-H "Flint-Version: 2026-09-07"Redirect to Flint's consent screen, or to the partner callback with an OAuth error. Error values before consent are unsupported_response_type, invalid_request, invalid_scope, and server_error. After the merchant decides, Flint redirects to redirect_uri with the code, state, and mode query parameters when they approve, or with an OAuth error when they deny.
No response body.
Preview partner install#
/v1/oauth/authorize/previewNo API key required
Rate limit: per IP
Validates the install link inputs and returns the partner app metadata and requested permissions for the consent screen. This route takes no credential. Flint ignores an Authorization header, except that a partner install access token is refused with 401. Flint ignores unrecognized parameters.
Query parameters
response_typeenumOAuth response type. Must be code.
code
client_idstringRequiredPartner app client ID.
redirect_uristringRequiredRegistered redirect URI for the partner app.
modeenumRequiredInstall mode.
testlive
code_challengestringBase64url-encoded SHA-256 hash of your code_verifier, without padding (RFC 7636).
code_challenge_methodenumPKCE challenge method.
S256
scopestringSpace-separated permission IDs from your app's permission manifest. Omit to request default_requested_permissions. Required permissions are always granted.
sandbox_idstringOptional active merchant sandbox ID, accepted only with mode=test. When omitted in test mode, Flint uses the merchant's default sandbox.
statestringOpaque state value returned to the partner callback.
Response · 200
The validated install preview.
dataobjectRequiredResource, collection, or operation result returned by this request.
client_idstringRequiredThe app's client ID, as sent in the authorization request.
modeenumRequiredWhether the install is for test or live mode.
testlive
namestringRequiredThe app's current name.
partner_app_idstringRequiredID of the partner app asking for access.
partner_app_versionintegerRequiredThe app’s version. It changes whenever the app is edited.
redirect_uristringRequiredThe registered redirect URI Flint sends the merchant back to after they approve or deny.
requested_permission_idsarray of stringRequiredIDs of the requested permissions, sorted. They are the permissions named in scope, or the app's default requested permissions when scope is omitted, plus every required permission.
requested_permissionsarray of objectRequiredThe requested permissions with the title, description, and scopes the consent screen shows, in the same order as requested_permission_ids.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl "https://api.withflintpay.com/v1/oauth/authorize/preview?client_id=fpc_00112233445566778899aabbccddeeff&redirect_uri=example&mode=test" \
-H "Flint-Version: 2026-09-07"The validated install preview.
{
"data": {
"client_id": "fpc_1234567890abcdef1234567890abcd",
"mode": "test",
"name": "Acme Commerce Plugin",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"partner_app_version": 1,
"redirect_uri": "https://plugins.acme.com/flint/oauth/callback",
"requested_permission_ids": [
"manage_orders",
"read_catalog"
],
"requested_permissions": [
{
"description": "Read and update Flint orders for installed merchants.",
"permission_id": "manage_orders",
"required_scopes": [
"commerce.orders.read",
"commerce.orders.write"
],
"title": "Manage orders"
},
{
"description": "Read product, variant, bundle, and SKU lookup catalog records.",
"optional": true,
"permission_id": "read_catalog",
"required_scopes": [
"commerce.bundles.read",
"commerce.catalog.read",
"commerce.products.read"
],
"title": "Read catalog"
}
]
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6A0M396VXB1MXTTQPBVRH"
}Was this helpful?
