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)
- Your Client ID (associated with your API key)
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 /industries.
curl -X POST https://api.dolfinai.co/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"
}'
{
"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. Each user is assigned the Member role.
User 1: Alice
curl -X POST https://api.dolfinai.co/organisations/9a658587-fe02-402e-b1ac-bfaf53274ef8/users \
-H "x-dolfin-api-key: dol_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"email": "alice@acmeplumbing.co.uk",
"name": "Alice Johnson"
}'
{
"userId": "a1111111-1111-1111-1111-111111111111",
"email": "alice@acmeplumbing.co.uk",
"name": "Alice Johnson",
"organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
"role": "Member"
}
User 2: Bob
curl -X POST https://api.dolfinai.co/organisations/9a658587-fe02-402e-b1ac-bfaf53274ef8/users \
-H "x-dolfin-api-key: dol_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"email": "bob@acmeplumbing.co.uk",
"name": "Bob Smith"
}'
{
"userId": "b2222222-2222-2222-2222-222222222222",
"email": "bob@acmeplumbing.co.uk",
"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/auth/codes \
-H "x-dolfin-api-key: dol_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"userId": "a1111111-1111-1111-1111-111111111111",
"organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8"
}'
{
"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/auth/exchange \
-H "Content-Type: application/json" \
-d '{
"code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"userId": "a1111111-1111-1111-1111-111111111111",
"email": "alice@acmeplumbing.co.uk",
"organisations": [
{
"organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
"organisationName": "Acme Plumbing Ltd",
"role": "Member"
}
]
}
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/invoices \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"
Sequence Diagram
Summary
| Phase | Endpoint | Called by | Auth |
|---|
| Create org | POST /organisations | Your backend | API key |
| Create users | POST /organisations/{orgId}/users | Your backend | API key |
| Generate code | POST /auth/codes | Your backend | API key |
| Exchange code | POST /auth/exchange | User’s browser | None (public) |
| Use API | Any endpoint | User’s browser | Bearer token |
