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/authorizeRequires 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.

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.

Error codes

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

Preview partner install#

GET/v1/oauth/authorize/previewNo 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.

testlive
permission_idsstring

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

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

INVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
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/tokenNo 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.

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

Error codes

AUTH_REQUIREDINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
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