flintDocs

Partner OAuth

Partner OAuth is the install flow that connects a Flint merchant to your partner app. Send the merchant's browser to the hosted authorize endpoint with your client_id, redirect_uri, and requested permission IDs. Flint handles sign-in, merchant selection, and permission review, then redirects back to you with an authorization code. That browser request is unauthenticated on your side; only the token exchange uses your app credentials.

Exchange the code at the token endpoint, passing your client_id and client_secret in the request body, to receive a partner install access token scoped to the granting merchant. The same endpoint rotates refresh tokens. Use the preview endpoint to validate an install request and see the normalized permission set Flint will show the merchant before you send them through.

Note:

See the Partner app installs guide for the full flow, and the partner apps reference for registering apps and managing installs.

Authorize partner install#

GET/v1/oauth/authorize

Requires a bearer token

Authenticates the merchant in Flint, validates the requested partner app install, and redirects back to the partner's redirect_uri with an authorization code.

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
permission_idsstring

Optional comma-delimited permission IDs. When omitted, Flint uses the app's default requested permissions.

environment_idstring

Optional explicit merchant environment ID. When omitted, Flint uses the merchant's default environment for the selected mode.

merchant_idstring

Optional preferred merchant selection for multi-merchant users.

statestringRequired

Opaque state value returned to the partner callback.

curl https://api.withflintpay.com/v1/oauth/authorize \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Preview partner install#

GET/v1/oauth/authorize/preview

No API key required

Validates the install link inputs and returns the partner app metadata and requested permissions for the consent screen.

Query parameters

client_idstringRequired

Partner app client ID.

redirect_uristringRequired

Registered redirect URI for the partner app.

modeenumRequired

Install mode.

  • test
  • live
permission_idsstring

Optional comma-delimited permission IDs. When omitted, Flint uses the app's default requested permissions.

Response · 200

dataobjectRequired
metaobject
request_idstring
curl https://api.withflintpay.com/v1/oauth/authorize/preview \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "app_type": "plugin",
    "client_id": "fpc_1234567890abcdef1234567890abcd",
    "mode": "test",
    "name": "Acme Commerce Plugin",
    "partner_app_id": "papp_01JQPARTNERAPP1234567890",
    "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",
        "title": "Manage orders"
      },
      {
        "description": "Read product, variant, bundle, and SKU lookup catalog records.",
        "optional": true,
        "permission_id": "read_catalog",
        "title": "Read catalog"
      }
    ]
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Exchange an OAuth token#

POST/v1/oauth/token

No API key required

Exchanges an authorization code or refresh token for an installation-scoped bearer token. This endpoint follows OAuth token endpoint conventions: it accepts application/x-www-form-urlencoded requests as well as JSON and returns OAuth token error objects for token exchange failures instead of the normal Flint error envelope. The public client flint-cli also supports the RFC 8628 device_code grant and rotating refresh tokens using form requests. Pending device requests return authorization_pending; early polling returns slow_down and increases the required interval by five seconds; denial returns access_denied; expired or consumed codes return expired_token. Access tokens last 15 minutes. CLI sessions expire after 30 days idle or 90 days total. Reusing a rotated refresh token revokes its family, including when the previous response was lost. A fresh browser login is then required. With session_mode=contexts at authorization, tokens include oauth_session_id and context_id. Refresh requires an explicitly authorized context_id; invalid_context and context_access_denied do not consume the refresh token. Each access token is limited to one context. Ordinary rotation preserves other unexpired access tokens; removing consent immediately invalidates affected tokens. Legacy sessions retain their original response and authorization semantics.

Request body

client_idstringRequired
client_secretstringRequired
codestring
grant_typeenumRequired
  • authorization_code
  • refresh_token
redirect_uristring
refresh_tokenstring

Response · 200

At least one of these shapes

access_tokenstringRequired
environment_grant_idstringRequired
expires_inintegerRequired
merchant_idstringRequired
modeenumRequired
  • test
  • live
partner_app_idstringRequired
partner_app_install_idstringRequired
refresh_tokenstring
scopestring
token_typeenumRequired
  • bearer
curl -X POST https://api.withflintpay.com/v1/oauth/token \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "fpc_1234567890abcdef1234567890abcd",
    "client_secret": "example",
    "code": "fpac_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
    "grant_type": "authorization_code",
    "redirect_uri": "https://plugins.acme.com/flint/oauth/callback"
  }'

Was this helpful?