Organizations

Organizations are hierarchy nodes used for delegated access, merchant grouping, and settings inheritance. A merchant can belong to one organization node, and settings policies attached to an organization constrain every descendant scope below it.

External API keys can access organizations within the authenticated merchant's organization subtree.

Organizations and their memberships are shared across test and live mode. Creating, updating, or deleting organizations, changing memberships, and transferring ownership require live mode. The accounts.organizations.write scope is available only on live keys.

For signup requests containing the exact starter-scope bundle used by older CLI versions, Flint issues a sandbox key without organization write access and returns a BOOTSTRAP_SCOPES_REDUCED warning in meta.warnings. Other explicit requests for this scope on test keys are rejected. Existing test keys with this scope are rejected; replace them with test keys that omit it, or use a live key for organization changes.

Root organization creation is reserved for Flint-managed setup; public callers create child organizations by providing a parent_organization_id. Each organization carries direct user memberships with owner, admin, operator, or viewer roles and supports ownership transfer. Deletion is rejected while the organization still has active descendant organizations or is linked to an active merchant; after deletion the organization's status is deleted.

Organization-scoped settings policies are managed through the settings API with scope=organization.

The Organization object#

Every field on an organization, as returned by retrieve and carried by the endpoints below.

Attributes

created_atstring

RFC3339 timestamp.

metadatamap of string

namestringRequired

organization_idstringRequired

parent_organizationobject or null

parent_organization_idstring

statusenumRequired

active
deleted

updated_atstring

RFC3339 timestamp.

JSON

{
  "created_at": "2026-03-18T09:15:00Z",
  "metadata": {
    "segment": "enterprise"
  },
  "name": "Northeast Region",
  "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
  "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB",
  "status": "active",
  "updated_at": "2026-03-18T09:15:00Z"
}

List organizations#

GET/v1/organizations

Requires scope accounts.organizations.read or accounts.organizations.write

Returns the organizations accessible to the caller, filtered to the authenticated merchant's organization subtree for external API keys.

Query parameters

parent_organization_idstring

Optional parent organization filter.

statusenum

Optional organization status filter.

active
deleted

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

sort_byenum

Sort field.

name
created_at
updated_at

sort_directionenum

Sort direction.

asc
desc

created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

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

JSON

{
  "data": [
    {
      "created_at": "2026-03-18T09:15:00Z",
      "metadata": {
        "segment": "enterprise"
      },
      "name": "Northeast Region",
      "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
      "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB",
      "status": "active",
      "updated_at": "2026-03-18T09:15:00Z"
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create organization#

POST/v1/organizationsIdempotent

Requires scope accounts.organizations.write

Creates a child organization within the caller's accessible organization hierarchy.

Request body

metadatamap of string

namestringRequired

parent_organization_idstring

Response · 201

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/organizations \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {
      "segment": "enterprise"
    },
    "name": "Northeast Region",
    "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB"
  }'

Get organization#

GET/v1/organizations/{organization_id}

Requires scope accounts.organizations.read or accounts.organizations.write

Returns an accessible organization by ID.

Path parameters

organization_idstringRequired

Flint organization ID.

Query parameters

expandarray of enum

Supported expansions: parent_organization. Expansion requires accounts.organizations.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Repeat expand, for example expand=parent_organization&expand=parent_organization, or pass one comma-separated value.

parent_organization

Response · 200

Same response as Create organization.

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

JSON

{
  "data": {
    "created_at": "2026-03-18T09:15:00Z",
    "metadata": {
      "segment": "enterprise"
    },
    "name": "Northeast Region",
    "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
    "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB",
    "status": "active",
    "updated_at": "2026-03-18T09:15:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update organization#

PATCH/v1/organizations/{organization_id}Idempotent

Requires scope accounts.organizations.write

Applies a sparse update to an accessible organization.

Path parameters

organization_idstringRequired

Flint organization ID.

Request body

metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API.

namestring

parent_organization_idstring

Response · 200

Same response as Create organization.

curl -X PATCH https://api.withflintpay.com/v1/organizations/org_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {
      "segment": "retail"
    },
    "name": "Northeast Retail"
  }'

Delete organization#

DELETE/v1/organizations/{organization_id}Idempotent

Requires scope accounts.organizations.write

Soft-deletes an organization when it has no active descendants or merchant links.

Path parameters

organization_idstringRequired

Flint organization ID.

Response · 200

Same response as Create organization.

curl -X DELETE https://api.withflintpay.com/v1/organizations/org_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

List organization memberships#

GET/v1/organizations/{organization_id}/memberships

Requires scope accounts.organizations.read or accounts.organizations.write

Returns the direct memberships for an organization.

Path parameters

organization_idstringRequired

Flint organization 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

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

JSON

{
  "data": [
    {
      "created_at": "2026-03-18T10:00:00Z",
      "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
      "role": "admin",
      "status": "active",
      "updated_at": "2026-03-18T10:00:00Z",
      "user_id": "usr_01JQ4X9G7C2R9M18D1T9EAV1KX"
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Grant organization membership#

POST/v1/organizations/{organization_id}/membershipsIdempotent

Requires scope accounts.organizations.write

Adds or updates a direct organization membership for a user.

Path parameters

organization_idstringRequired

Flint organization ID.

Request body

roleenumRequired

owner
admin
operator
viewer

user_idstringRequired

Response · 200

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/organizations/org_123/memberships \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "role": "admin",
    "user_id": "usr_01JQ4X9G7C2R9M18D1T9EAV1KX"
  }'

Revoke organization membership#

DELETE/v1/organizations/{organization_id}/memberships/{user_id}Idempotent

Requires scope accounts.organizations.write

Revokes a direct organization membership for a user.

Path parameters

organization_idstringRequired

Flint organization ID.

user_idstringRequired

Flint user ID.

Response · 200

dataobjectRequired

metaobject

request_idstring

curl -X DELETE https://api.withflintpay.com/v1/organizations/org_123/memberships/usr_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Transfer organization ownership#

POST/v1/organizations/{organization_id}/transfer-ownershipIdempotent

Requires scope accounts.organizations.write

Transfers the organization owner role to another user.

Path parameters

organization_idstringRequired

Flint organization ID.

Request body

new_owner_user_idstringRequired

Response · 200

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/organizations/org_123/transfer-ownership \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "new_owner_user_id": "usr_01JQ4XB5PSE2K16K5M89KFBXW7"
  }'

Was this helpful?