FlintflintDocs

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.

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

Endpoints

Authorize partner install#

GET/v1/oauth/authorize

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.

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

Bash
curl https://api.withflintpay.com/v1/oauth/authorize \
  -H "Authorization: Bearer YOUR_API_KEY"

Preview partner install#

GET/v1/oauth/authorize/preview

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.

testlive
permission_idsstring

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

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/oauth/authorize/preview \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "partner_app_id": "papp_01JQPARTNERAPP1234567890",
    "client_id": "fpc_1234567890abcdef1234567890abcd",
    "name": "Acme Commerce Plugin",
    "app_type": "plugin",
    "redirect_uri": "https://plugins.acme.com/flint/oauth/callback",
    "mode": "test",
    "requested_permission_ids": [
      "manage_orders",
      "read_catalog"
    ],
    "requested_permissions": [
      {
        "permission_id": "manage_orders",
        "title": "Manage orders",
        "description": "Read and update Flint orders for installed merchants."
      },
      {
        "permission_id": "read_catalog",
        "title": "Read catalog",
        "description": "Read product, variant, bundle, and SKU lookup catalog records.",
        "optional": true
      }
    ]
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Exchange partner install token#

POST/v1/oauth/token

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.

Request body
client_idstringrequired
client_secretstringrequired
codestring
grant_typestringrequired
redirect_uristring
refresh_tokenstring
Response · 200
access_tokenstringrequired
environment_grant_idstringrequired
expires_inintegerrequired
merchant_idstringrequired
modeenumrequired
testlive
partner_app_idstringrequired
partner_app_install_idstringrequired
refresh_tokenstring
scopestring
token_typestringrequired
Bash
curl -X POST https://api.withflintpay.com/v1/oauth/token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "fpc_1234567890abcdef1234567890abcd",
    "client_secret": "fps_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
    "code": "fpac_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
    "redirect_uri": "https://plugins.acme.com/flint/oauth/callback"
  }'
JSON
{
  "access_token": "fpat_v1.c2FtcGxlLXBhcnRuZXItaW5zdGFsbC10b2tlbg",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "fprt_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
  "scope": "commerce.orders.read commerce.orders.write",
  "merchant_id": "mer_123",
  "partner_app_id": "papp_01JQPARTNERAPP1234567890",
  "partner_app_install_id": "pinst_01JQPARTNERINSTALL123456",
  "environment_grant_id": "egrt_01JQPARTNERGRANT12345678",
  "mode": "test"
}
Rate this doc