Client Integration

This guide walks through the complete integration flow for a client platform that wants to onboard SMB users into Dolfin. By the end, your users will have session tokens they can use to interact with the Dolfin API directly from the browser.

Prerequisites

A Dolfin API key (distributed during onboarding)

Overview

The integration follows three phases:

Create an organisation and users

Your backend creates an organisation and provisions users into it using your API key.

Generate auth codes

When a user needs to access Dolfin, your backend generates a short-lived auth code for that user.

Exchange for a session token

The user’s browser exchanges the auth code for a session JWT, which is used for all subsequent API calls.

Step 1: Create an Organisation

First, create an organisation for the SMB business. You’ll need an industryId - retrieve the list of available industries from GET /v1/industries.

curl -X POST https://api.dolfinai.co/v1/organisations \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Plumbing Ltd",
    "industryId": "b2d4f6a8-1234-5678-9abc-def012345678"
  }'

const response = await fetch('https://api.dolfinai.co/v1/organisations', {
  method: 'POST',
  headers: {
    'x-dolfin-api-key': 'dol_live_abc123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Plumbing Ltd',
    industryId: 'b2d4f6a8-1234-5678-9abc-def012345678',
  }),
});

const organisation = await response.json();
console.log(organisation.id); // "9a658587-fe02-402e-b1ac-bfaf53274ef8"

Response:

{
  "id": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "name": "Acme Plumbing Ltd",
  "clientId": "c1234567-abcd-ef01-2345-6789abcdef01",
  "industry": {
    "id": "b2d4f6a8-1234-5678-9abc-def012345678",
    "name": "Plumbing & HVAC"
  },
  "createdAt": "2025-01-15T10:30:00Z"
}

Store the id from the response - this is the organisationId you’ll use in all subsequent calls.

Step 2: Create Users

Now create users within the organisation. Pass an optional role — Member, Admin, or Owner — to set what the user can do. Omit it and the user is created as a Member. Provisioning with your API key acts with your client’s authority, so you can grant any role, including Owner. Most integrators make the person who signs up for the organisation its Owner, and add colleagues as Member or Admin.

A user acting with a session token can never grant a role above their own — an Admin can add Members and Admins, but not an Owner. Attempting it returns 403 User.RoleAboveCaller.

User 1: Alice

curl -X POST https://api.dolfinai.co/v1/organisations/9a658587-fe02-402e-b1ac-bfaf53274ef8/users \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Alice Johnson",
    "role": "Owner"
  }'

const user1 = await fetch(
  'https://api.dolfinai.co/v1/organisations/9a658587-fe02-402e-b1ac-bfaf53274ef8/users',
  {
    method: 'POST',
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: '[email protected]',
      name: 'Alice Johnson',
      role: 'Owner',
    }),
  }
).then(r => r.json());

Response:

{
  "userId": "a1111111-1111-1111-1111-111111111111",
  "email": "[email protected]",
  "name": "Alice Johnson",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "role": "Owner"
}

User 2: Bob

curl -X POST https://api.dolfinai.co/v1/organisations/9a658587-fe02-402e-b1ac-bfaf53274ef8/users \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Bob Smith"
  }'

const user2 = await fetch(
  'https://api.dolfinai.co/v1/organisations/9a658587-fe02-402e-b1ac-bfaf53274ef8/users',
  {
    method: 'POST',
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: '[email protected]',
      name: 'Bob Smith',
    }),
  }
).then(r => r.json());

Response:

{
  "userId": "b2222222-2222-2222-2222-222222222222",
  "email": "[email protected]",
  "name": "Bob Smith",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "role": "Member"
}

If a user with the same email already exists, they will be added to the organisation rather than duplicated. A 409 Conflict is returned if the user is already a member of that organisation.

Step 3: Generate an Auth Code

When a user needs to access Dolfin (e.g. they click “Open Invoicing” in your app), generate a short-lived auth code from your backend.

curl -X POST https://api.dolfinai.co/v1/auth/codes \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "a1111111-1111-1111-1111-111111111111"
  }'

const authCode = await fetch('https://api.dolfinai.co/v1/auth/codes', {
  method: 'POST',
  headers: {
    'x-dolfin-api-key': 'dol_live_abc123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 'a1111111-1111-1111-1111-111111111111',
    organisationId: '9a658587-fe02-402e-b1ac-bfaf53274ef8',
  }),
}).then(r => r.json());

// Pass authCode.code to the user's browser
console.log(authCode.code);      // "eyJhbGciOiJIUzI1NiIs..."
console.log(authCode.expiresAt); // "2025-01-15T10:40:00Z"

Response:

{
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-01-15T10:40:00Z"
}

Auth codes expire after 10 minutes and are single-use. Generate a new code each time the user needs to authenticate.

Step 4: Exchange the Auth Code for a Session Token

Pass the auth code to the user’s browser (e.g. as a URL parameter in a redirect). The browser then exchanges it for a session JWT. This call is made from the browser and does not require an API key.

curl -X POST https://api.dolfinai.co/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

const session = await fetch('https://api.dolfinai.co/v1/auth/exchange', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code: authCode, // the code from the URL parameter
  }),
}).then(r => r.json());

// Store the token for subsequent API calls
localStorage.setItem('dolfin_token', session.token);

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "a1111111-1111-1111-1111-111111111111",
  "email": "[email protected]",
  "organisations": [
    {
      "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
      "organisationName": "Acme Plumbing Ltd",
      "role": "Owner"
    }
  ]
}

The session token is a JWT valid for 8 hours.

Step 5: Make Authenticated API Calls

The user can now call any Dolfin API endpoint using the session token:

curl -X GET https://api.dolfinai.co/v1/invoices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"

const invoices = await fetch('https://api.dolfinai.co/v1/invoices', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('dolfin_token')}`,
    'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
  },
}).then(r => r.json());

Sequence Diagram

Summary

Phase	Endpoint	Called by	Auth
Create org	`POST /v1/organisations`	Your backend	API key
Create users	`POST /v1/organisations/{orgId}/users`	Your backend	API key
Generate code	`POST /v1/auth/codes`	Your backend	API key
Exchange code	`POST /v1/auth/exchange`	User’s browser	None (public)
Use API	Any endpoint	User’s browser	Bearer token

Getting started

Accounts Payable

Accounts Receivable

Client Integration

Prerequisites

Overview

Step 1: Create an Organisation

Step 2: Create Users

User 1: Alice

User 2: Bob

Step 3: Generate an Auth Code

Step 4: Exchange the Auth Code for a Session Token

Step 5: Make Authenticated API Calls

Sequence Diagram

Summary

​Prerequisites

​Overview

​Step 1: Create an Organisation

​Step 2: Create Users

​User 1: Alice

​User 2: Bob

​Step 3: Generate an Auth Code

​Step 4: Exchange the Auth Code for a Session Token

​Step 5: Make Authenticated API Calls

​Sequence Diagram

​Summary

Prerequisites

Overview

Step 1: Create an Organisation

Step 2: Create Users

User 1: Alice

User 2: Bob

Step 3: Generate an Auth Code

Step 4: Exchange the Auth Code for a Session Token

Step 5: Make Authenticated API Calls

Sequence Diagram

Summary