Act as a client via API

Use this guide when your integration calls HR, Payroll, Pay, or Books on behalf of a merchant you manage as a SERVICE_PARTNER. Acting-client headers tell the gateway which client company to scope — without creating a separate org per merchant.

Prerequisites

Machine JWT from token exchange
workspaceId and companyId for the target merchant
partner:client:act-as permission (included in partner workspace lead roles)

Overview

Layer	What it identifies
Bearer JWT	Who is calling (your partner org, `tenantId`)
`X-Workspace-Id`	Which workspace owns the client
`X-Acting-Company-Id`	Which merchant you are operating on

Both acting headers must be sent together on every product API request. They are optional in the OpenAPI schema but required in practice for partner multi-merchant integrations.

Steps

Exchange credentials for a machine token

curl -sS -X POST "$FLUIDE_BASE_URL/api/v1/authorize/token" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Api-Secret: $FLUIDE_API_SECRET" \
  -H "X-Fluide-Client-Id: fluide-developer"

JWT tenantId is your partner organization — not the client’s.

Call a product API with acting headers

curl -sS "$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"

In the API reference playground: Authorize for Bearer + API key, then fill X-Workspace-Id and X-Acting-Company-Id on the endpoint form.

Switch merchants in your app

When an admin selects a different merchant in your UI, swap only the header values — the same JWT and API key stay valid:

const headers = {
  Authorization: `Bearer ${accessToken}`,
  'X-Fluide-Api-Key': process.env.FLUIDE_API_KEY,
  'X-Fluide-Client-Id': 'fluide-developer',
  'X-Workspace-Id': merchant.workspaceId,
  'X-Acting-Company-Id': merchant.companyId,
};

Tips

Store workspaceId + companyId per merchant at onboarding time — Onboard a client company.
Permissions are intersected at the gateway: you only get module permissions your partner role allows and that are valid for acting-client mode.
Auth routes (workspaces, companies, token exchange) do not use acting headers.

Troubleshooting

Problem	Resolution
Data from wrong merchant	Verify both headers match the intended company and that `company.workspaceId` matches `X-Workspace-Id`.
`403` despite valid token	Missing `partner:client:act-as` or private workspace visibility. Check org role and workspace membership.
Empty results but no error	Headers omitted — request scoped to partner org without a client context.

Multi-tenancy

Full tenancy model and setup flow.

Authorization

Token exchange and header reference.

Overview

Service partner

HR & People

HR Operations

Payroll

Pay

Books

Access & Auth

Utils

Playbooks

Act as a client via API

Act as a client via API

Prerequisites

Overview

Steps

Tips

Troubleshooting

Multi-tenancy

Authorization

​Act as a client via API

​Prerequisites

​Overview

​Steps

​Tips

​Troubleshooting

​Related

Multi-tenancy

Authorization

Act as a client via API

Prerequisites

Overview

Steps

Tips

Troubleshooting

Related