Skip to content

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#

  1. Your server redirects the merchant's browser to GET /v1/oauth/authorize with a state and a PKCE challenge.
  2. Flint shows the consent screen. The merchant signs in, chooses a merchant, and chooses Install app or Deny.
  3. Flint redirects the browser to your redirect_uri with code, state, and mode, or with an error.
  4. Your backend sends the code and its code_verifier to POST /v1/oauth/token and 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:

  • state and the PKCE pair belong together. For each install attempt, generate a random state and a code_verifier of 43 to 128 URL-safe characters, and store them together. Send code_challenge, the unpadded base64url SHA-256 hash of the verifier, which is always 43 characters. code_challenge_method must be S256; plain isn't supported.
  • redirect_uri must 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.
  • scope lists permission IDs, not API scopes. Use IDs from your app's permission manifest, separated by spaces. Omit scope to request the app's default_requested_permissions. Flint always adds the manifest's required permissions, the ones without optional: true.
  • sandbox_id works only with mode=test. It picks the sandbox the test grant uses. Without it, Flint uses the merchant's default sandbox.
  • merchant_id is 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:

JavaScript
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.

Text
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.

ProblemWhat 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:

errorCause
access_deniedThe merchant chose Deny.
invalid_requeststate 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_scopescope is empty or names a permission that isn't in your manifest.
unsupported_response_typeresponse_type isn't code.
server_errorFlint 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
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, and mode are required. Flint validates response_type, state, code_challenge, and code_challenge_method when you send them, and ignores merchant_id.
  • It never redirects. Every problem comes back as a Flint error envelope, such as 400 INVALID_REQUEST with param sandbox_id for a sandbox_id sent with mode=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:

MethodSend
Self-signed client assertionclient_assertion: a new JWT for each request, signed by the key of a public_key or jwks_url credential.
Workload identity assertionclient_assertion: a token from the issuer of a workload_identity credential. It can be reused until it expires.
Client secretHTTP 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.

Partner app installsRegister credentials, run the install flow, and handle refresh, webhooks, and disconnects.Partner apps referenceCreate apps, register credentials, and list installs.

Authorize partner install#

GET/v1/oauth/authorize

No 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_typeenumRequired

OAuth response type. Must be code.

  • code
client_idstringRequired

Partner app client ID.

redirect_uristringRequired

Registered redirect URI for the partner app.

modeenumRequired

Install mode.

  • test
  • live
code_challengestringRequired

Base64url-encoded SHA-256 hash of your code_verifier, without padding (RFC 7636).

code_challenge_methodenumRequired

PKCE challenge method.

  • S256
scopestring

Space-separated permission IDs from your app's permission manifest. Omit to request default_requested_permissions. Required permissions are always granted.

sandbox_idstring

Optional active merchant sandbox ID, accepted only with mode=test. When omitted in test mode, Flint uses the merchant's default sandbox.

merchant_idstring

Optional merchant to preselect on the consent screen when the person can access several merchants.

statestringRequired

Opaque 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#

GET/v1/oauth/authorize/preview

No 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_typeenum

OAuth response type. Must be code.

  • code
client_idstringRequired

Partner app client ID.

redirect_uristringRequired

Registered redirect URI for the partner app.

modeenumRequired

Install mode.

  • test
  • live
code_challengestring

Base64url-encoded SHA-256 hash of your code_verifier, without padding (RFC 7636).

code_challenge_methodenum

PKCE challenge method.

  • S256
scopestring

Space-separated permission IDs from your app's permission manifest. Omit to request default_requested_permissions. Required permissions are always granted.

sandbox_idstring

Optional active merchant sandbox ID, accepted only with mode=test. When omitted in test mode, Flint uses the merchant's default sandbox.

statestring

Opaque state value returned to the partner callback.

Response · 200

The validated install preview.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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.

JSON
{
  "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?