Partner apps

Partner apps are installable integrations that Flint merchants connect to your product. The surface has three parts: register and manage the app, send merchants through the hosted OAuth install flow, and exchange the returned authorization code for install access tokens scoped to that merchant.

An app declares a permission manifest (named permission groups that map to Flint API scopes), and merchants review and approve those permissions during install. Each install records per-environment grants you can inspect and revoke individually or all at once. The app's client_secret is returned only at creation and rotation, and a partner app can register its own webhook endpoint to receive install lifecycle events.

The Partner app installs guide covers the end-to-end flow from registration through token exchange. For a merchant's own webhook endpoints on regular resources, see the webhooks reference instead.

Endpoints

GET/v1/developer/partner/apps
POST/v1/developer/partner/apps
GET/v1/developer/partner/apps/{partner_app_id}
GET/v1/developer/partner/apps/{partner_app_id}/installs
GET/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}
POST/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}/environment-grants/{environment_grant_id}/revoke
POST/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}/revoke
POST/v1/developer/partner/apps/{partner_app_id}/rotate-secret

List partner apps #

GET/v1/developer/partner/apps

Returns partner apps owned by the authenticated merchant.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200

dataarray of objectrequired

metaobject

next_page_tokenstring

request_idstring

Bash

curl https://api.withflintpay.com/v1/developer/partner/apps \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": [
    {
      "partner_app_id": "papp_01JQPARTNERAPP1234567890",
      "name": "Acme Commerce Plugin",
      "status": "active",
      "visibility": "private",
      "app_type": "plugin",
      "client_id": "fpc_1234567890abcdef1234567890abcd",
      "redirect_uris": [
        "https://plugins.acme.com/flint/oauth/callback",
        "http://localhost:3000/flint/oauth/callback"
      ],
      "permission_manifest": [
        {
          "permission_id": "manage_orders",
          "title": "Manage orders",
          "description": "Read and update Flint orders for installed merchants.",
          "required_scopes": [
            "commerce.orders.read",
            "commerce.orders.write"
          ]
        },
        {
          "permission_id": "manage_customers",
          "title": "Manage customers",
          "description": "Read and update customer records for installed merchants.",
          "required_scopes": [
            "customers.customers.read",
            "customers.customers.write"
          ],
          "optional": true
        },
        {
          "permission_id": "read_catalog",
          "title": "Read catalog",
          "description": "Read product, variant, bundle, and SKU lookup catalog records.",
          "required_scopes": [
            "commerce.products.read",
            "commerce.bundles.read",
            "commerce.catalog.read"
          ],
          "optional": true
        },
        {
          "permission_id": "manage_bundles",
          "title": "Manage bundles",
          "description": "Create and update bundle catalog records for installed merchants.",
          "required_scopes": [
            "commerce.bundles.write"
          ],
          "optional": true
        }
      ],
      "default_requested_permissions": [
        "manage_orders"
      ],
      "allowed_scopes": [
        "commerce.bundles.read",
        "commerce.bundles.write",
        "commerce.catalog.read",
        "commerce.orders.read",
        "commerce.orders.write",
        "commerce.products.read",
        "customers.customers.read",
        "customers.customers.write"
      ],
      "created_at": "2026-03-18T20:00:00Z",
      "updated_at": "2026-03-18T20:00:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create partner app #

POST/v1/developer/partner/appsIdempotent

Creates a partner app owned by the authenticated merchant. Use a developer setup session during setup or a normal external API key afterward.

Request body

app_typestring

default_requested_permissionsarray of string

namestringrequired

permission_manifestarray of objectrequired

redirect_urisarray of stringrequired

visibilitystring

Response · 201

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/developer/partner/apps \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Acme Commerce Plugin",
    "visibility": "private",
    "app_type": "plugin",
    "redirect_uris": [
      "https://plugins.acme.com/flint/oauth/callback",
      "http://localhost:3000/flint/oauth/callback"
    ],
    "permission_manifest": [
      {
        "permission_id": "manage_orders",
        "title": "Manage orders",
        "description": "Read and update Flint orders for installed merchants.",
        "required_scopes": [
          "commerce.orders.read",
          "commerce.orders.write"
        ]
      },
      {
        "permission_id": "manage_customers",
        "title": "Manage customers",
        "description": "Read and update customer records for installed merchants.",
        "required_scopes": [
          "customers.customers.read",
          "customers.customers.write"
        ],
        "optional": true
      },
      {
        "permission_id": "read_catalog",
        "title": "Read catalog",
        "description": "Read product, variant, bundle, and SKU lookup catalog records.",
        "required_scopes": [
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "optional": true
      },
      {
        "permission_id": "manage_bundles",
        "title": "Manage bundles",
        "description": "Create and update bundle catalog records for installed merchants.",
        "required_scopes": [
          "commerce.bundles.write"
        ],
        "optional": true
      }
    ],
    "default_requested_permissions": [
      "manage_orders"
    ]
  }'

JSON

{
  "data": {
    "partner_app_id": "papp_01JQPARTNERAPP1234567890",
    "name": "Acme Commerce Plugin",
    "status": "active",
    "visibility": "private",
    "app_type": "plugin",
    "client_id": "fpc_1234567890abcdef1234567890abcd",
    "redirect_uris": [
      "https://plugins.acme.com/flint/oauth/callback",
      "http://localhost:3000/flint/oauth/callback"
    ],
    "permission_manifest": [
      {
        "permission_id": "manage_orders",
        "title": "Manage orders",
        "description": "Read and update Flint orders for installed merchants.",
        "required_scopes": [
          "commerce.orders.read",
          "commerce.orders.write"
        ]
      },
      {
        "permission_id": "manage_customers",
        "title": "Manage customers",
        "description": "Read and update customer records for installed merchants.",
        "required_scopes": [
          "customers.customers.read",
          "customers.customers.write"
        ],
        "optional": true
      },
      {
        "permission_id": "read_catalog",
        "title": "Read catalog",
        "description": "Read product, variant, bundle, and SKU lookup catalog records.",
        "required_scopes": [
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "optional": true
      },
      {
        "permission_id": "manage_bundles",
        "title": "Manage bundles",
        "description": "Create and update bundle catalog records for installed merchants.",
        "required_scopes": [
          "commerce.bundles.write"
        ],
        "optional": true
      }
    ],
    "default_requested_permissions": [
      "manage_orders"
    ],
    "allowed_scopes": [
      "commerce.bundles.read",
      "commerce.bundles.write",
      "commerce.catalog.read",
      "commerce.orders.read",
      "commerce.orders.write",
      "commerce.products.read",
      "customers.customers.read",
      "customers.customers.write"
    ],
    "created_at": "2026-03-18T20:00:00Z",
    "updated_at": "2026-03-18T20:00:00Z",
    "client_secret": "fps_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get partner app #

GET/v1/developer/partner/apps/{partner_app_id}

Returns a single partner app owned by the authenticated merchant.

Path parameters

partner_app_idstringrequired

Flint partner app ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl https://api.withflintpay.com/v1/developer/partner/apps/papp_01JQPARTNERAPP1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "partner_app_id": "papp_01JQPARTNERAPP1234567890",
    "name": "Acme Commerce Plugin",
    "status": "active",
    "visibility": "private",
    "app_type": "plugin",
    "client_id": "fpc_1234567890abcdef1234567890abcd",
    "redirect_uris": [
      "https://plugins.acme.com/flint/oauth/callback",
      "http://localhost:3000/flint/oauth/callback"
    ],
    "permission_manifest": [
      {
        "permission_id": "manage_orders",
        "title": "Manage orders",
        "description": "Read and update Flint orders for installed merchants.",
        "required_scopes": [
          "commerce.orders.read",
          "commerce.orders.write"
        ]
      },
      {
        "permission_id": "manage_customers",
        "title": "Manage customers",
        "description": "Read and update customer records for installed merchants.",
        "required_scopes": [
          "customers.customers.read",
          "customers.customers.write"
        ],
        "optional": true
      },
      {
        "permission_id": "read_catalog",
        "title": "Read catalog",
        "description": "Read product, variant, bundle, and SKU lookup catalog records.",
        "required_scopes": [
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "optional": true
      },
      {
        "permission_id": "manage_bundles",
        "title": "Manage bundles",
        "description": "Create and update bundle catalog records for installed merchants.",
        "required_scopes": [
          "commerce.bundles.write"
        ],
        "optional": true
      }
    ],
    "default_requested_permissions": [
      "manage_orders"
    ],
    "allowed_scopes": [
      "commerce.bundles.read",
      "commerce.bundles.write",
      "commerce.catalog.read",
      "commerce.orders.read",
      "commerce.orders.write",
      "commerce.products.read",
      "customers.customers.read",
      "customers.customers.write"
    ],
    "created_at": "2026-03-18T20:00:00Z",
    "updated_at": "2026-03-18T20:00:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List partner app installs #

GET/v1/developer/partner/apps/{partner_app_id}/installs

Returns installs for a partner app owned by the authenticated merchant.

Path parameters

partner_app_idstringrequired

Flint partner app ID.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200

dataarray of objectrequired

metaobject

next_page_tokenstring

request_idstring

Bash

curl https://api.withflintpay.com/v1/developer/partner/apps/papp_01JQPARTNERAPP1234567890/installs \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": [
    {
      "partner_app_install_id": "pinst_01JQPARTNERINSTALL123456",
      "merchant_id": "mer_123",
      "status": "active",
      "granted_scopes": [
        "commerce.orders.read",
        "commerce.orders.write",
        "commerce.products.read",
        "commerce.bundles.read",
        "commerce.catalog.read"
      ],
      "installed_by_user_id": "usr_123",
      "environment_grants": [
        {
          "environment_grant_id": "egrt_01JQPARTNERGRANTTEST123456",
          "mode": "test",
          "environment_id": "test_01JQEXAMPLEDEFAULT12345678",
          "status": "active",
          "granted_scopes": [
            "commerce.orders.read",
            "commerce.orders.write",
            "commerce.products.read",
            "commerce.bundles.read",
            "commerce.catalog.read"
          ],
          "created_at": "2026-03-18T20:05:00Z",
          "updated_at": "2026-03-18T20:05:00Z"
        },
        {
          "environment_grant_id": "egrt_01JQPARTNERGRANTLIVE123456",
          "mode": "live",
          "environment_id": "menv_01JQEXAMPLELIVE123456789",
          "status": "active",
          "granted_scopes": [
            "commerce.orders.read",
            "commerce.orders.write",
            "commerce.products.read",
            "commerce.bundles.read",
            "commerce.catalog.read"
          ],
          "created_at": "2026-03-18T20:06:00Z",
          "updated_at": "2026-03-18T20:06:00Z"
        }
      ],
      "created_at": "2026-03-18T20:05:00Z",
      "updated_at": "2026-03-18T20:06:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get partner app install #

GET/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}

Returns a single install for a partner app owned by the authenticated merchant.

Path parameters

partner_app_idstringrequired

Flint partner app ID.

partner_app_install_idstringrequired

Flint partner app install ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl https://api.withflintpay.com/v1/developer/partner/apps/papp_01JQPARTNERAPP1234567890/installs/pinst_01JQPARTNERINSTALL123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "partner_app_install_id": "pinst_01JQPARTNERINSTALL123456",
    "merchant_id": "mer_123",
    "status": "active",
    "granted_scopes": [
      "commerce.orders.read",
      "commerce.orders.write",
      "commerce.products.read",
      "commerce.bundles.read",
      "commerce.catalog.read"
    ],
    "installed_by_user_id": "usr_123",
    "environment_grants": [
      {
        "environment_grant_id": "egrt_01JQPARTNERGRANTTEST123456",
        "mode": "test",
        "environment_id": "test_01JQEXAMPLEDEFAULT12345678",
        "status": "active",
        "granted_scopes": [
          "commerce.orders.read",
          "commerce.orders.write",
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "created_at": "2026-03-18T20:05:00Z",
        "updated_at": "2026-03-18T20:05:00Z"
      },
      {
        "environment_grant_id": "egrt_01JQPARTNERGRANTLIVE123456",
        "mode": "live",
        "environment_id": "menv_01JQEXAMPLELIVE123456789",
        "status": "active",
        "granted_scopes": [
          "commerce.orders.read",
          "commerce.orders.write",
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "created_at": "2026-03-18T20:06:00Z",
        "updated_at": "2026-03-18T20:06:00Z"
      }
    ],
    "created_at": "2026-03-18T20:05:00Z",
    "updated_at": "2026-03-18T20:06:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Revoke environment grant #

POST

/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}/environment-grants/{environment_grant_id}/revoke

Idempotent

Revokes a single test or live environment grant for a partner app install.

Path parameters

partner_app_idstringrequired

Flint partner app ID.

partner_app_install_idstringrequired

Flint partner app install ID.

environment_grant_idstringrequired

Flint environment grant ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/developer/partner/apps/papp_01JQPARTNERAPP1234567890/installs/pinst_01JQPARTNERINSTALL123456/environment-grants/egrt_01JQPARTNERGRANTTEST123456/revoke \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "partner_app_install_id": "pinst_01JQPARTNERINSTALL123456",
    "merchant_id": "mer_123",
    "status": "active",
    "granted_scopes": [
      "commerce.orders.read",
      "commerce.orders.write",
      "commerce.products.read",
      "commerce.bundles.read",
      "commerce.catalog.read"
    ],
    "installed_by_user_id": "usr_123",
    "environment_grants": [
      {
        "environment_grant_id": "egrt_01JQPARTNERGRANTTEST123456",
        "mode": "test",
        "environment_id": "test_01JQEXAMPLEDEFAULT12345678",
        "status": "active",
        "granted_scopes": [
          "commerce.orders.read",
          "commerce.orders.write",
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "created_at": "2026-03-18T20:05:00Z",
        "updated_at": "2026-03-18T20:05:00Z"
      },
      {
        "environment_grant_id": "egrt_01JQPARTNERGRANTLIVE123456",
        "mode": "live",
        "environment_id": "menv_01JQEXAMPLELIVE123456789",
        "status": "active",
        "granted_scopes": [
          "commerce.orders.read",
          "commerce.orders.write",
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "created_at": "2026-03-18T20:06:00Z",
        "updated_at": "2026-03-18T20:06:00Z"
      }
    ],
    "created_at": "2026-03-18T20:05:00Z",
    "updated_at": "2026-03-18T20:06:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Revoke partner app install #

POST/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}/revokeIdempotent

Revokes a partner app install and all of its environment grants.

Path parameters

partner_app_idstringrequired

Flint partner app ID.

partner_app_install_idstringrequired

Flint partner app install ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/developer/partner/apps/papp_01JQPARTNERAPP1234567890/installs/pinst_01JQPARTNERINSTALL123456/revoke \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "partner_app_install_id": "pinst_01JQPARTNERINSTALL123456",
    "merchant_id": "mer_123",
    "status": "active",
    "granted_scopes": [
      "commerce.orders.read",
      "commerce.orders.write",
      "commerce.products.read",
      "commerce.bundles.read",
      "commerce.catalog.read"
    ],
    "installed_by_user_id": "usr_123",
    "environment_grants": [
      {
        "environment_grant_id": "egrt_01JQPARTNERGRANTTEST123456",
        "mode": "test",
        "environment_id": "test_01JQEXAMPLEDEFAULT12345678",
        "status": "active",
        "granted_scopes": [
          "commerce.orders.read",
          "commerce.orders.write",
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "created_at": "2026-03-18T20:05:00Z",
        "updated_at": "2026-03-18T20:05:00Z"
      },
      {
        "environment_grant_id": "egrt_01JQPARTNERGRANTLIVE123456",
        "mode": "live",
        "environment_id": "menv_01JQEXAMPLELIVE123456789",
        "status": "active",
        "granted_scopes": [
          "commerce.orders.read",
          "commerce.orders.write",
          "commerce.products.read",
          "commerce.bundles.read",
          "commerce.catalog.read"
        ],
        "created_at": "2026-03-18T20:06:00Z",
        "updated_at": "2026-03-18T20:06:00Z"
      }
    ],
    "created_at": "2026-03-18T20:05:00Z",
    "updated_at": "2026-03-18T20:06:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Rotate partner app secret #

POST/v1/developer/partner/apps/{partner_app_id}/rotate-secretIdempotent

Rotates the client secret for a partner app owned by the authenticated merchant. The new client_secret is only returned once.

Path parameters

partner_app_idstringrequired

Flint partner app ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/developer/partner/apps/papp_01JQPARTNERAPP1234567890/rotate-secret \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "partner_app_id": "papp_01JQPARTNERAPP1234567890",
    "client_id": "fpc_1234567890abcdef1234567890abcd",
    "client_secret": "fps_rotated1234567890abcdef1234567890abcdef1234567890abcdef12"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Rate this doc