Multi-tenancy

Fluide APIs are multi-tenant by design. Every product route (HR, Payroll, Pay, Books, Utils) scopes data to a tenant context resolved from your JWT and request headers. This page explains the two tenancy models Connect developers need to understand, when to use each, and which APIs to call.

Two tenancy models

Model	Who uses it	Tenant unit	How context is set
Organization tenant	Fluide Business users and direct integrations	One organization per customer	JWT `tenantId` + active org membership
Partner / ISV	Fluide Connect developers serving many merchants	Workspace → client company	Machine JWT + `X-Workspace-Id` + `X-Acting-Company-Id`

These models can coexist. A SERVICE_PARTNER org has its own organization record and manages separate client companies under workspaces.

Organization tenancy (direct)

Use this when your integration acts inside a single Fluide organization — for example automating HR for one business that owns the API credentials.

How it works

A user or machine token is bound to an active organization (tenantId in the JWT).
The gateway forwards requests with enriched user context (X-User-Object, RBAC permissions).
Product services filter all reads and writes to that organization.

Key Auth APIs

API	Purpose
`GET/POST /api/v1/organizations`	List and create organizations
`POST /api/v1/organizations/active`	Switch the active organization on the current session
`GET /api/v1/organizations/{id}/members`	Org membership and roles
`GET /api/v1/auth/me`	Current user, session, `orgMemberRole`, permissions

Org roles include owner, admin, member, and viewer. Custom org roles with permission strings are also supported. See RBAC.

Token response

After sign-in or token exchange, the access token envelope includes tenantId:

{
  "accessToken": "eyJ...",
  "exp": 1710000000,
  "tenantId": "09cb501e-865b-4092-978c-dbb7b30841bd",
  "fluideClientId": "fluide-developer"
}

If a user belongs to multiple organizations, call POST /api/v1/organizations/active before product API calls that should target a specific org. The JWT always reflects the active organization.

Required headers (direct)

Header	Value
`Authorization`	`Bearer <accessToken>`
`X-Fluide-Api-Key`	Your `fl_dev_...` developer key
`X-Fluide-Client-Id`	`fluide-developer`

See Authorization for the full machine-token flow.

Partner tenancy (ISV / multi-merchant)

Use this when your product serves many end-customers (merchants, employers, payers) and you call Fluide APIs on their behalf. Developers onboard as SERVICE_PARTNER organizations in Fluide Connect. You do not register a separate OAuth app per merchant. Instead you use:

One developer API key (fl_dev_...) and machine JWT
Workspaces — logical containers for your integration (e.g. production vs sandbox, or per region)
Client companies — each merchant you onboard under a workspace
Acting-client headers — tell the gateway which company each request targets

Setup flow

Complete developer onboarding

Sign in to Connect, verify your developer account, and provision API credentials via POST /api/v1/auth/developer/ensure.

Create a workspace

POST /api/v1/workspaces with a name. List workspaces with GET /api/v1/workspaces.

Add client companies

POST /api/v1/workspaces/{workspaceId}/companies with company name, country, and currency. Each company is a distinct tenant context for product APIs.

Submit client KYB (when required)

For regulated products, upload documents and submit via POST .../workspaces/{workspaceId}/companies/{companyId}/kyb/submit. See the client KYB guide for the full flow.

Call product APIs with acting-client headers

Exchange your API key for a machine token, then pass workspace and company on every gateway request (see below).

Acting-client headers

After POST /api/v1/authorize/token, include these on every product API call when acting for a specific merchant:

Header	Value
`Authorization`	`Bearer <machine-jwt>`
`X-Fluide-Api-Key`	Your `fl_dev_...` key
`X-Fluide-Client-Id`	`fluide-developer`
`X-Workspace-Id`	Workspace UUID
`X-Acting-Company-Id`	Client company UUID

The gateway resolves the effective tenant via GET /api/v1/auth-context/{jti} and forwards the correct org context to downstream services.

curl -X GET "$FLUIDE_BASE_URL/api/v1/hr/employees" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer" \
  -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
  -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID"

const res = await fetch(`${baseUrl}/api/v1/hr/employees`, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'X-Fluide-Api-Key': process.env.FLUIDE_API_KEY,
    'X-Fluide-Client-Id': 'fluide-developer',
    'X-Workspace-Id': workspaceId,
    'X-Acting-Company-Id': companyId,
  },
});

Store the active workspaceId and companyId in your integration layer (or pass them from your UI when an admin switches merchant). Missing acting-client headers on partner tokens will not scope requests to the intended end-customer.On each product API page in API reference, set optional X-Workspace-Id and X-Acting-Company-Id header fields in the playground (in addition to Authorize → Bearer + API key).

Workspace and company APIs

API	Method	Purpose
`/api/v1/workspaces`	`GET`, `POST`	List and create workspaces
`/api/v1/workspaces/{workspaceId}`	`PATCH`	Update workspace metadata
`/api/v1/workspaces/{workspaceId}/companies`	`GET`, `POST`	List and create client companies
`/api/v1/workspaces/{workspaceId}/companies/{companyId}`	`GET`, `PATCH`, `DELETE`	Manage a single company
`.../companies/{companyId}/kyb/submit`	`POST`	Submit client KYB for review

Browse full request and response schemas in the Auth API reference.

Choosing a model

Your integration	Use
Internal tool for one Fluide Business org	Organization tenancy only
SaaS product onboarding many merchants	Partner tenancy (workspaces + companies + acting headers)
Testing in sandbox before going live	Same model as production; use a dedicated workspace for test companies

What is not supported (today)

Expectation	Current Connect model
Separate OAuth client per end-customer	One developer API key per Connect account (`fluide-developer`)
Product API calls without tenant context	All business routes require Bearer auth; partners need acting-client headers
Dynamic marketplace app installs via Connect docs	Marketplace install APIs are separate from the Connect developer credential flow

Authorization

Token exchange and required headers for machine tokens.

How-to guides

Partner onboarding, HR, payroll, and cross-product playbooks.

RBAC

Organization roles, permissions, and validate-session payload.

HR → Payroll sync

Employee mirror and payroll run lifecycle.

Payroll → Books GL

GL mappings and journal posting after payroll completes.

​Multi-tenancy

​Two tenancy models

​Organization tenancy (direct)

​How it works

​Key Auth APIs

​Token response

​Required headers (direct)

​Partner tenancy (ISV / multi-merchant)

​Setup flow

​Acting-client headers

​Workspace and company APIs

​Choosing a model

​What is not supported (today)

​Related docs

Authorization

How-to guides

RBAC

HR → Payroll sync

Payroll → Books GL

Multi-tenancy

Two tenancy models

Organization tenancy (direct)

How it works

Key Auth APIs

Token response

Required headers (direct)

Partner tenancy (ISV / multi-merchant)

Setup flow

Acting-client headers

Workspace and company APIs

Choosing a model

What is not supported (today)

Related docs