Authorization - Fluide Connect

Fluide Connect uses a two-step model: exchange your developer API key and secret for a short-lived JWT, then call product APIs with the JWT and your API key.

Prerequisites

You already have a verified developer account and API credentials from the Connect dashboard (API Keys):

apiKey — e.g. fl_dev_...
apiSecret — shown once at provisioning; store it in your secret manager

If you need to view or rotate credentials, sign in to Connect. The API secret is never returned again from GET /api/v1/authorize/current.

Exchange key + secret for an access token

Send your credentials only to the token endpoint. Never include the secret on HR, payroll, payments, or other product routes.

API reference — POST /authorize/token

Interactive playground, request headers, and response schema.

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

const baseUrl = process.env.FLUIDE_BASE_URL;

const res = await fetch(`${baseUrl}/api/v1/authorize/token`, {
  method: 'POST',
  headers: {
    'X-Fluide-Api-Key': process.env.FLUIDE_API_KEY,
    'X-Fluide-Api-Secret': process.env.FLUIDE_API_SECRET,
    'X-Fluide-Client-Id': 'fluide-developer',
  },
});

if (!res.ok) throw new Error(`Token exchange failed: ${await res.text()}`);
const { accessToken } = await res.json();

Response (abbreviated):

{
  "accessToken": "eyJ...",
  "exp": 1710000000,
  "tenantId": "...",
  "fluideClientId": "fluide-developer",
  "authContextPath": "/api/v1/auth-context/..."
}

Use the API secret only for token exchange. Never send it on product API routes.

Test in the API playground

Every product endpoint in API reference includes an interactive playground. Requests without the right headers are rejected — you will see Authorization field missing or 401 if any are omitted.

Exchange a token first

Run the token exchange above (curl or Node.js). Copy the accessToken value.

Click Authorize on a product endpoint

Open any HR, Payroll, Pay, Books, or Utils endpoint and click Authorize. Fill in all three fields:

Playground field	Value
Bearer	Paste the raw JWT (`eyJ...`) — do not include the `Bearer` prefix
X-Fluide-Api-Key	Your `fl_dev_...` key (pre-filled with a placeholder; replace it)
X-Fluide-Client-Id	`fluide-developer` (pre-filled)

Send the request

Click Send. Health checks such as GET /api/v1/hr/health use the same headers as business endpoints — there is no anonymous access.

X-Fluide-Client-Id must match the client ID embedded in your access token (fluide-developer). X-Fluide-Api-Key must match the API key bound to that token.

Call Fluide APIs

Send both the Bearer token and your API key on every product request.

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

curl -X GET "$FLUIDE_BASE_URL/api/v1/hr/health" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer"

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

if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
const health = await res.json();

Cache the accessToken until exp and refresh before it expires. See First request for an end-to-end walkthrough.

For organization vs partner (multi-merchant) tenancy, see Multi-tenancy.

Partner acting-client headers (ISV / multi-merchant)

When you integrate many end-customers under your service partner org, product APIs need two extra headers on top of Bearer + API key:

Header	Value
`X-Workspace-Id`	Workspace UUID (from `GET /api/v1/workspaces`)
`X-Acting-Company-Id`	Client company UUID (from `GET /api/v1/workspaces/{id}/companies`)

In the API reference playground, these appear as optional header parameters on HR, Payroll, Pay, Books, and Utils endpoints — fill them in per request when scoping to a merchant. Direct single-org integrations can omit them.

curl -X GET "$FLUIDE_BASE_URL/api/v1/hr/employees?limit=10" \
  -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?limit=10`, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'X-Fluide-Api-Key': process.env.FLUIDE_API_KEY,
    'X-Fluide-Client-Id': 'fluide-developer',
    'X-Workspace-Id': process.env.FLUIDE_WORKSPACE_ID,
    'X-Acting-Company-Id': process.env.FLUIDE_COMPANY_ID,
  },
});

Rotate credentials

If a secret is exposed, rotate it from the Connect dashboard or with a valid Bearer session:

curl -X POST "$FLUIDE_BASE_URL/api/v1/authorize/rotate-secret" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Client-Id: fluide-developer"

const res = await fetch(`${baseUrl}/api/v1/authorize/rotate-secret`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${sessionToken}`,
    'X-Fluide-Client-Id': 'fluide-developer',
  },
});

if (!res.ok) throw new Error(`Rotate failed: ${await res.text()}`);
const { apiSecret } = await res.json();

Update your integration and exchange a new token with the new secret.

​Prerequisites

​Exchange key + secret for an access token

API reference — POST /authorize/token

​Test in the API playground

​Call Fluide APIs

​Partner acting-client headers (ISV / multi-merchant)

​Rotate credentials

Prerequisites

Exchange key + secret for an access token

Test in the API playground

Call Fluide APIs

Partner acting-client headers (ISV / multi-merchant)

Rotate credentials