Exchange API key for access token

cURL

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" \
  -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
  -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

const baseUrl = process.env.FLUIDE_BASE_URL;

const response = 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',
    'X-Workspace-Id': process.env.FLUIDE_WORKSPACE_ID,
    'X-Acting-Company-Id': process.env.FLUIDE_COMPANY_ID,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

import os
import requests

base_url = os.environ["FLUIDE_BASE_URL"]
headers = {
        "X-Fluide-Api-Key": os.environ["FLUIDE_API_KEY"],
        "X-Fluide-Api-Secret": os.environ["FLUIDE_API_SECRET"],
        "X-Fluide-Client-Id": "fluide-developer",
        "X-Workspace-Id": os.environ["FLUIDE_WORKSPACE_ID"],
        "X-Acting-Company-Id": os.environ["FLUIDE_COMPANY_ID"],
}

response = requests.post(
    f"{base_url}/api/v1/authorize/token",
    headers=headers,
    json={},
    timeout=30,
)
response.raise_for_status()
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String baseUrl = System.getenv("FLUIDE_BASE_URL");
HttpClient client = HttpClient.newHttpClient();
HttpRequest.Builder builder = HttpRequest.newBuilder()
    .uri(URI.create(baseUrl + "/api/v1/authorize/token"))
    .header("X-Fluide-Api-Key", System.getenv("FLUIDE_API_KEY"))
    .header("X-Fluide-Api-Secret", System.getenv("FLUIDE_API_SECRET"))
    .header("X-Fluide-Client-Id", "fluide-developer")
    .header("X-Workspace-Id", System.getenv("FLUIDE_WORKSPACE_ID"))
    .header("X-Acting-Company-Id", System.getenv("FLUIDE_COMPANY_ID"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{}"))
    .build();
HttpResponse<String> response = client.send(builder.build(), HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) throw new RuntimeException("HTTP " + response.statusCode() + ": " + response.body());
System.out.println(response.body());

<?php
$baseUrl = getenv("FLUIDE_BASE_URL");
$ch = curl_init($baseUrl . "/api/v1/authorize/token");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-Fluide-Api-Key: ' . getenv('FLUIDE_API_KEY'),
        'X-Fluide-Api-Secret: ' . getenv('FLUIDE_API_SECRET'),
        'X-Fluide-Client-Id: fluide-developer',
        'X-Workspace-Id: ' . getenv('FLUIDE_WORKSPACE_ID'),
        'X-Acting-Company-Id: ' . getenv('FLUIDE_COMPANY_ID'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => "{}",
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) throw new RuntimeException("HTTP $status: $response");
echo $response;

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    "accessToken": "<string>",
    "jti": "<string>",
    "tenantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "fluideClientId": "fluide-developer",
    "exp": 123,
    "iat": 123,
    "authContextPath": "/api/v1/auth-context/{jti}"
  }
}

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_FAILED",
  "statusCode": 400,
  "timestamp": "2026-06-03T12:00:00.000Z",
  "errors": {
    "from": [
      "from must be a valid date"
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_FAILED",
  "statusCode": 400,
  "timestamp": "2026-06-03T12:00:00.000Z",
  "errors": {
    "from": [
      "from must be a valid date"
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_FAILED",
  "statusCode": 400,
  "timestamp": "2026-06-03T12:00:00.000Z",
  "errors": {
    "from": [
      "from must be a valid date"
    ]
  }
}

POST

api

authorize

token

cURL

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" \
  -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
  -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

const baseUrl = process.env.FLUIDE_BASE_URL;

const response = 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',
    'X-Workspace-Id': process.env.FLUIDE_WORKSPACE_ID,
    'X-Acting-Company-Id': process.env.FLUIDE_COMPANY_ID,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

import os
import requests

base_url = os.environ["FLUIDE_BASE_URL"]
headers = {
        "X-Fluide-Api-Key": os.environ["FLUIDE_API_KEY"],
        "X-Fluide-Api-Secret": os.environ["FLUIDE_API_SECRET"],
        "X-Fluide-Client-Id": "fluide-developer",
        "X-Workspace-Id": os.environ["FLUIDE_WORKSPACE_ID"],
        "X-Acting-Company-Id": os.environ["FLUIDE_COMPANY_ID"],
}

response = requests.post(
    f"{base_url}/api/v1/authorize/token",
    headers=headers,
    json={},
    timeout=30,
)
response.raise_for_status()
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String baseUrl = System.getenv("FLUIDE_BASE_URL");
HttpClient client = HttpClient.newHttpClient();
HttpRequest.Builder builder = HttpRequest.newBuilder()
    .uri(URI.create(baseUrl + "/api/v1/authorize/token"))
    .header("X-Fluide-Api-Key", System.getenv("FLUIDE_API_KEY"))
    .header("X-Fluide-Api-Secret", System.getenv("FLUIDE_API_SECRET"))
    .header("X-Fluide-Client-Id", "fluide-developer")
    .header("X-Workspace-Id", System.getenv("FLUIDE_WORKSPACE_ID"))
    .header("X-Acting-Company-Id", System.getenv("FLUIDE_COMPANY_ID"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{}"))
    .build();
HttpResponse<String> response = client.send(builder.build(), HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) throw new RuntimeException("HTTP " + response.statusCode() + ": " + response.body());
System.out.println(response.body());

<?php
$baseUrl = getenv("FLUIDE_BASE_URL");
$ch = curl_init($baseUrl . "/api/v1/authorize/token");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-Fluide-Api-Key: ' . getenv('FLUIDE_API_KEY'),
        'X-Fluide-Api-Secret: ' . getenv('FLUIDE_API_SECRET'),
        'X-Fluide-Client-Id: fluide-developer',
        'X-Workspace-Id: ' . getenv('FLUIDE_WORKSPACE_ID'),
        'X-Acting-Company-Id: ' . getenv('FLUIDE_COMPANY_ID'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => "{}",
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) throw new RuntimeException("HTTP $status: $response");
echo $response;

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    "accessToken": "<string>",
    "jti": "<string>",
    "tenantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "fluideClientId": "fluide-developer",
    "exp": 123,
    "iat": 123,
    "authContextPath": "/api/v1/auth-context/{jti}"
  }
}

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_FAILED",
  "statusCode": 400,
  "timestamp": "2026-06-03T12:00:00.000Z",
  "errors": {
    "from": [
      "from must be a valid date"
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_FAILED",
  "statusCode": 400,
  "timestamp": "2026-06-03T12:00:00.000Z",
  "errors": {
    "from": [
      "from must be a valid date"
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_FAILED",
  "statusCode": 400,
  "timestamp": "2026-06-03T12:00:00.000Z",
  "errors": {
    "from": [
      "from must be a valid date"
    ]
  }
}

Authorizations

X-Fluide-Api-Key

string

header

default:fl_dev_your_key

required

Developer API key (fl_dev_...). Required on every API call with a machine access token.

X-Fluide-Api-Secret

string

header

required

API secret used only during token exchange. Never send on product routes.

X-Fluide-Client-Id

string

header

default:fluide-developer

required

First-party client audience. Must match the fluide_client_id claim on the JWT. Use fluide-developer for Connect.

Headers

X-Fluide-Api-Key

string

required

Developer API key (fl_dev_...).

X-Fluide-Api-Secret

string

required

API secret — use only on this route, never on product APIs.

X-Fluide-Client-Id

string

default:fluide-developer

required

Must be fluide-developer for Connect integrations.

X-Workspace-Id

string<uuid>

Partner / ISV only: UUID of the workspace that owns the client company. Required together with X-Acting-Company-Id when scoping product APIs to a merchant. See /getting-started/multi-tenancy.

X-Acting-Company-Id

string<uuid>

Partner / ISV only: UUID of the client company to act on. Must belong to the workspace in X-Workspace-Id.

Body

application/json

apiKey

string

Optional if sent via header.

apiSecret

string

Optional if sent via header.

organizationId

string<uuid>

Optional active organization override for the issued token.

Response

Access token issued

success

boolean

required

Whether the request succeeded

Example:

true

message

string

required

Human-readable outcome message (localized when i18n is configured)

Example:

"Operation completed successfully"

data

object

Response payload when success is true

Show child attributes

Auth API

HR API

Payroll API

Pay API

Books API

Utils API

Exchange API key for access token

Authorizations

Headers

Body

Response