Connect your CRM or ERP to Iwana in a few hours. An API key for one workspace, OAuth 2.0 for a user who authorises you, the whole API from the first key, and signed webhooks.
REST JSON API keys OAuth 2.0 HMAC webhooks Full access
Three steps to your first successful request. Everything is configured from the pro dashboard.
Create an API keySettings → Developers → New key. Copy the secret straight away — it is shown once. Shipping a product that several businesses will install? Use OAuth, below.
Test authenticationCall GET /integrations/me to check the organisation and the active permissions.
Sync your dataRead the catalogue and the team, create or update clients and appointments, then subscribe a webhook for real-time updates.
Two ways to reach a workspace, both landing on the same API, the same /pro/* routes and the same permission checks. An API key names the workspace; an OAuth token names the user, the workspace and your application. Neither manages credentials (API keys, webhooks, plugins) nor invokes the AI: those stay in the app.
API key
OAuth token
Who issues it
A workspace OWNER/ADMIN, in Settings → Developers
The user, on the consent page, for one PRO workspace
What it names
The workspace
The user and the workspace and the app
Permissions
The whole API described here
The whole API, within the user’s role, re-checked on every request
Lifetime
Until revoked
Access 1 h · refresh 3 years · until revoked
Revoked by
Workspace admin · Iwana staff
Workspace admin (“Connected apps”) · Iwana staff (deactivating the app)
Header
Authorization: Bearer iw_live_…
Authorization: Bearer iwa_at_…
Authorization: Bearer iw_live_<prefix>_<secret>
Production keys
Prefix iw_live_* — access to the organisation’s real data.
Test keys
Prefix iw_test_* — reads the workspace’s real data and refuses every write (403 test_key_read_only): enough to build an integration end to end without touching the diary. It is not a separate demo workspace, and none exists. The refusal comes before the body is read — on every POST, PUT, PATCH and DELETE, read-only previews included — so body validation (400 validation_failed) can only be exercised with a live key.
The organisation is embedded in the key or the token: you do not need to send x-workspace-id or any other context header.
OAuth 2.0 — Sign in with IWANA
Authorization Code with a client secret. PKCE (S256) is honoured when the client sends it and not required. Tokens are opaque: no OpenID Connect, no JWKS, no id_token — identity comes from GET /oauth/userinfo. The token opens the whole API described here, within the user’s role: a VIEWER’s token cannot write.
Endpoint
Method
Auth
https://iwana.fr/v3/oauth/authorize
browser
the user’s Iwana session
https://iwana.fr/v3/api/v1/oauth/token
POST, form-encoded
client_id + client_secret (body or HTTP Basic)
https://iwana.fr/v3/api/v1/oauth/userinfo
GET
Bearer iwa_at_…
1. Register your app
Iwana staff create the app: name, logo, up to five redirect_uris matched exactly (http or https, no fragment). You receive a client_id (iwa_…) and a client_secret (iwa_cs_…) — the secret is shown once and stored hashed. Every app is confidential: the secret is required at the token endpoint, PKCE adds to it but does not replace it.
Write to [email protected] with the app name, a logo and your callback URLs.
2. Send the user to Iwana
GET https://iwana.fr/v3/oauth/authorize
?client_id=iwa_…
&redirect_uri=https://crm.example/auth/iwana/callback
&response_type=code
&state=<random>
&code_challenge=<S256>&code_challenge_method=S256
No scope parameter: the token covers the whole API. An unknown client_id or a redirect_uri that is not registered shows a dead-end page and never redirects. A user without a PRO workspace sees “reserved for professionals”; with several workspaces, they pick which one to authorise. A remembered consent skips the card.
The browser comes back to redirect_uri?code=iwa_ac_…&state=…, or ?error=access_denied&state=… if the user refused. The code lives 60 seconds and works once.
3. Exchange the code
POST https://iwana.fr/v3/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=iwa_ac_…&redirect_uri=<same as step 2>
&client_id=iwa_…&client_secret=iwa_cs_…&code_verifier=…
Send code_verifier only if you sent a code_challenge in step 2. The client may authenticate in the body or with HTTP Basic.
4. Call the API
GET https://iwana.fr/v3/api/v1/pro/clients
Authorization: Bearer iwa_at_…
No x-workspace-id header: the token carries the workspace. Writes made this way are attributed to your app in the audit log, and an appointment created this way carries source: API.
Returns a new access_token; the refresh_token stays the same. After three years, or once the grant is revoked, the answer is invalid_grant and the user must sign in again. Refresh at the hour mark rather than per request: the token endpoint has its own, much smaller limit.
sub + org_id is the pair to link to your own user record.
OAuth errors
The token endpoint speaks RFC 6749: { "error": "invalid_grant", "error_description": "…" } with invalid_request, invalid_client (401, with WWW-Authenticate), invalid_grant, unsupported_grant_type. A rejected bearer on any PRO route is a 401 with the usual { "error": { "code": "invalid_token" } } envelope.
Lifetimes
What
Lives
Then
Authorization code
60 s, one use
invalid_grant
Access token
1 hour
refresh
Refresh token
3 years, flat
the user signs in again
Grant
until revoked
every token dead at once
API key
until revoked
401
Revocation
There is no revocation endpoint: the workspace admin cuts your app off from Settings → Developers → Connected apps, and Iwana staff can deactivate the app everywhere. Either way every token is refused from the next request on, including a freshly refreshed access token. A member who is removed or suspended loses their tokens the same way.
With a generic library
Any standard OAuth 2.0 client works. Two configurations ready to paste:
The examples below omit this prefix for readability. Identifiers (`id`, `clientId`, `orgId`…) are opaque, unprefixed strings: store them as they are, do not parse them.
Check your key
GET/integrations/me
Returns orgId, actor, permissions, locale and timezone. Ideal as an integration health check.
What holds for every route, and what the OpenAPI specification spells out operation by operation.
Unknown fields: refused on the way in, ignored on the way out
A request body (or a query string with declared parameters) carrying a field that is not declared is refused with 400 validation_failed — it is not silently dropped; so is a number that is not one (limit=abc). The other way round, a response may gain fields without notice: ignore the ones you do not know.
Success codes and delete answers
A create answers 201. Reads, updates, deletes and the POSTs that only compute — /clients/import/check, /companies/lists/preview, /communications/preview, /workflows/{id}/test, /map/route — answer 200. A delete is never a 204: it answers a small JSON body, { "ok": true } on most routes and { "id": "…", "deleted": true } on /companies and /companies/lists; each operation’s response in the specification says which.
Retries: Idempotency-Key
On creates — POST /appointments, /clients, /contacts, /companies, /sites, /equipments, /quotes, /invoices (and from-quote, from-intervention, from-contract), /invoices/{id}/payments, /invoices/{id}/credit-note, /quotes/dpgf, quote and project duplication, /interventions, /projects, /tasks, /contracts — send Idempotency-Key: <8 to 128 characters>. The same key on the same route within 48 h returns the first response instead of creating a duplicate. An error is not stored: retry it with the same key. Other routes ignore the header.
Your ids and duplicates
POST /clients creates a record on every call without id: it never matches an existing record by email or phone. Deduplication is yours: record the mapping with PUT /external-refs and look it up with GET /external-refs before creating (answer { "item": null } when nothing matches).
Updates
Three forms, stated on each operation: a POST that creates or updates depending on id; a field-by-field PATCH{ "field": "…", "value": … } (quotes, invoices, contracts, equipment, interventions, projects); a classic partial PATCH (sites). Amounts named …Cents are cents; a service’s price is euros.
Source and AI
An appointment written with a key or a token carries source: API, unless the body sends its own source. A key never calls the AI: workflow generation and PDF extraction answer 403 scope_required and are not in the specification. An automation saved with a key cannot add or change a Léo step, a template included: 403 scope_required, details.reason: ai_step_session_only. Léo steps a person wrote stay as they are.
ERP modules
Equipment, contracts, quotes, invoices, interventions and the price library need the ERP modules in the workspace’s plan; otherwise the answer is 402 erp_required. When the ERP offer is switched off for the whole platform the answer is 403 offer_disabled (with details.offer = "erp"), whatever the subscription.
Lists and paging
List
Page size (default / max)
Shape
/appointments, /sites
200 / 500
{ items, total, limit, offset }
/clients, /contacts
50 / 100
{ items, total, limit, offset }
/companies
50 / 200
{ items, total }
/equipments, /interventions, /projects
200 / 500
{ items, total }
/contracts
300 / 500
{ items, total }
/quotes, /invoices
500 / 500
{ items, total }
/tasks
500, no paging
{ items, total, cap }
/activity-log, documents
limit + before cursor
{ items, nextBefore }
Catalogue, team, settings
the whole list
array or { items }
A /clients list without kind returns individuals only: send kind=ALL to include companies. Each operation’s response schema says which of these shapes it returns.
Team
Workspace members and teams: a member's membership id is what an appointment's memberIds expects. A key can also invite people and organise teams.
GET/team
Members (membership id = an appointment’s memberIds), teams and who is in which.
POST/team/members/invite
Invites a colleague into the workspace (not a client): an invitation email valid 14 days. OWNER role refused.
POST/team/teams
Creates or renames a team; POST /team/teams/{id}/members to add a member.
Appointments
Appointments (type=APPOINTMENT) and blocked slots (type=UNAVAILABILITY, including those imported from Google or Outlook) go through the same routes; lists return appointments unless you ask for type=UNAVAILABILITY. The source is marked API when called with a key or a token, unless the body sends its own.
GET/appointments
Paginated list (limit 200 by default, 500 at most). Filters: from, to (ISO date), status or statuses (comma-separated: PENDING, CONFIRMED, EXPIRED…), clientId, siteId, companyId, projectId, memberIds, serviceIds, search.
GET/appointments/{id}
One appointment with its client, service, site, assigned crew and intervention report.
GET/appointments/{id}/history
The appointment’s log: edits, status changes, messages sent.
GET/appointments/counts
Counts per tab: upcoming, today, requests, cancelled, history.
POST/appointments
Creates an appointment, or updates it when the body carries its id (an unknown id answers 404, never a create). serviceId is required to create, clientId optional; startAt / endAt in ISO 8601 UTC, required on an update too. An omitted field keeps its value, null clears it. Send an Idempotency-Key header so a retry never creates a duplicate.
PATCH/appointments/{id}/status
Changes the status (e.g. CONFIRMED, COMPLETED, CANCELLED) without rewriting the whole object. Emits appointment.updated, or appointment.cancelled for CANCELLED.
DELETE/appointments/{id}
Cancels and removes the appointment: afterwards GET answers 404 and lists no longer return it. To keep a cancelled appointment visible, set its status to CANCELLED instead.
GET/calendar/events
A diary window: appointments, blocked slots, closed days (from / to).
GET/availability/resolve
Effective working windows per member and day (from / to). A range over 62 days (inclusive) is refused with 400 range_too_long: split longer periods into several calls.
POST/availability/schedules
Creates or updates a member’s planning; an overlap answers 409 schedule_conflict.
The address book. /clients holds individuals (kind=INDIVIDUAL) and companies (kind=COMPANY); /companies is its company view, /contacts the people attached to an account. A client is not a team member: for a colleague, see POST /team/members/invite.
GET/clients
Paginated list (50 by default, 100 at most) with search over name, email and phone. Without kind, individuals only: kind=ALL for everything, kind=COMPANY for companies. view=list for a lighter answer.
GET/clients/{id}
Full record: contact details, tags, custom fields, number of contacts and sites.
POST/clients
Creates a record, or updates it when the body carries its id. Without id it always creates: no matching on email or phone. Deduplicate with /external-refs. A company SIRET already used answers 409 siret_already_used (details.clientId names the record). Idempotency-Key accepted.
DELETE/clients/{id}
Deletes the record (soft delete: it leaves lists and GET answers 404).
GET/clients/{id}/duplicates
Possible duplicates: same SIRET or same name. Read-only.
POST/clients/{id}/merge
Merges this duplicate into targetId: appointments, sites, quotes… move to the target, the source record goes to the bin.
POST/clients/{id}/convert
Individual ↔ company, keeping the id and everything attached to it.
POST/clients/import
Bulk import (20,000 rows at most); with target, matching on email, phone, SIRET or name and a skip / update / create choice.
POST/clients/{id}/portal-link
Link to the customer portal, created once then reused. Sends nothing.
POST/clients/{id}/documents
Uploads a document (base64 data URL, 14 MB at most); GET for the list.
POST/contacts
Creates or updates a person attached to an account (clientId required to create).
POST/companies
Creates or updates a company (name required); a SIRET already used answers 409 siret_already_used, as on /clients. GET /companies for the list (50 by default, 200 at most).
A site is an address where the work happens: a contact usually has several, and it is the site — not the contact — that carries the gate code, GPS coordinates and the people to reach on the spot. A piece of equipment is what is installed there, a maintenance contract what covers it.
GET/sites
The workspace’s addresses (200 by default, 500 at most). Filter with ?clientId=, ?clientIds= or ?companyId=.
GET/sites/{id}
One site with its contacts (owner, agency, tenant…).
POST/sites
Creates a site (create only). An owner is required: clientId or companyId — without one, 400 owner_required; line1 is optional; lat/lng if you already have them.
PATCH/sites/{id}
Updates a site: an omitted field keeps its value, null clears it.
POST/sites/{id}/contacts
Replaces the list of people at the site.
GET/equipments
Installed equipment. Filter with ?siteId=, ?clientId= or ?companyId=.
POST/equipments
Creates an equipment item: label and clientId required, siteId must belong to the same client.
PATCH/equipments/{id}
Updates one field: { field, value }; an unknown name goes to customFields.
GET/contracts
Maintenance contracts (300 by default, 500 at most).
POST/contracts
Creates a contract: clientId and startsOn required; lines and covered equipment afterwards.
POST/contracts/{id}/equipment/sync
Replaces the whole set of covered equipment and their cadence.
A site belongs to a contact or a company, and a piece of equipment to a client and optionally to one of its sites: create the contact before the site, and filter equipment with ?siteId= to find what is installed at one address. Equipment and contracts need the ERP modules.
Projects (chantiers) & tasks
A chantier groups phases, work items, rooms, reserves, measurements, documents, parties and partner companies. The tasks of /tasks are the workspace’s to-do list, separate from a chantier’s work items.
GET/projects
Chantiers (200 by default, 500 at most); counts=1 for counts per status.
POST/projects
Creates a draft chantier (reference CH-…). Idempotency-Key accepted.
The catalogue (services, locations, categories, specialties — read it to map your IDs before creating appointments; a key can also change it), business rules, custom fields, automations and the messages sent to clients.
GET/catalog/services
Services on offer with variants, category and locations: duration (durationMinutes), price in euros. The whole list, no paging.
POST/catalog/services
Creates or updates a service (name and durationMinutes required). On an update, send the whole service.
GET/catalog/locations
Places of business (addresses, zones, online).
GET/catalog/categories
Service categories.
GET/catalog/specialties
Who can perform each service: members, teams, crew size.
GET/business-rules
Business rule definitions and values (lead times, cancellation…); POST to change one.
GET/fields
Custom fields of one record type (?scope=client, appointment…). Values live in customFields, under the field’s key.
GET/workflows/bootstrap
The list of automations and published templates.
POST/workflows
Creates a draft automation (from a template, a spec or blank); PATCH …/status to activate it.
POST/workflows/{id}/test
A dry run on a real record: shows what each step would do, sends nothing.
POST/workflows/runs/{runId}/approve
Approves a waiting run: the rest, sends included, runs.
GET/communications/history/{id}
One sent message in full, with its delivery dates.
PATCH/communications/notifications/{id}
Switches a client notification on or off.
Drafting workflows with AI is not open to keys. Test sends from /communications/notifications/…/test really go out (an SMS is billed): send to, a key has no account address.
Statistics, activity log & geo
Dashboard indicators, the workspace’s activity log and address tools.
GET/dashboard/stats
KPIs, series and breakdowns over a period (range=7d, 30d, 90d, ytd, mtd or custom).
GET/dashboard/home
Home tiles: open quotes, unpaid invoices, revenue this month.
GET/activity-log
Activity feed, newest first: limit (50 by default, 200 at most), before cursor, kinds filter.
GET/geo/suggest
Address autocomplete (6 suggestions); /geo/resolve to geocode.
The figures are the dashboard’s, recomputed on every call: cache them rather than re-reading them in a loop.
External ID mapping
Iwana does not deduplicate for you: POST /clients without id always creates. For an idempotent sync, store the correspondence between your IDs and Iwana’s, and look it up before creating.
provider and entityType are free text (hubspot, client…): pick values and keep them.
Outgoing webhooks
Subscribe an HTTPS URL from Settings → Developers. Iwana sends a JSON POST on every event, signed so you can verify authenticity. The body is always { event, orgId, data, occurredAt }. data stays short: the record’s id, related ids, the status, ISO dates and amounts in cents — no names, notes or addresses, except a contact’s email and name in client.created / client.updated. Re-read the record with GET when you need all of it.
HMAC verification — compute the SHA-256 HMAC of the raw body (JSON as sent) with the secret shown once when the subscription was created. Compare with Iwana-Signature. Answer 2xx within 15 seconds. Each event is delivered once — there is no automatic retry today. Failures are visible in Settings → Developers; to catch up on a missed event, periodically re-read the lists (GET /appointments?from=&to=, GET /clients, GET /invoices…).
Errors
Every error has the same shape and carries the identifier of the request that produced it. Quote requestId when you write to us about a call: it is also returned in the X-Request-Id header on every response, successes included.
Conflict with what exists (a SIRET already used, on /clients and /companies alike)
schedule_conflict, siret_already_used
429
Workspace budget exhausted
rate_limited
Rate limits
The budget belongs to the workspace, and all of its API keys and OAuth tokens spend the same one. The people using the dashboard each have their own, so an integration that loops cannot lock its own customer out.
Window
Per workspace, all keys and tokens together
Headers
1 minute
600 requests
X-RateLimit-Limit, -Remaining, -Reset (seconds)
24 hours
50,000 requests
X-RateLimit-Limit-Day, -Remaining-Day, -Reset-Day
These are the defaults; Iwana staff can change them platform-wide, so read the X-RateLimit-Limit* headers rather than hard-coding the numbers. Past either window the answer is 429 with the usual envelope, error.code = "rate_limited", and a Retry-After header in seconds. A per-IP floor of 1,000 requests/minute also applies before authentication, under the same unsuffixed header names: a call refused by the credential or permission checks (401, a 403 such as test_key_read_only, a 402) carries only those per-IP headers — no -Day ones — and does not spend the workspace budget.
Pace on X-RateLimit-Remaining and back off on 429. Refresh access tokens at the hour mark, not per request.
Versioning
Current version: v1 (/api/v1/pro/…). Breaking changes will be published under /v2/ with an overlap of at least 12 months on v1.
Backwards-compatible additions (new optional fields, new endpoints) may arrive without a major version bump. Treat unknown fields in a response as normal: your client must not fail because we added one. In a request it is the other way round: an undeclared field is refused with 400 validation_failed.
OpenAPI
This whole page also exists in machine-readable form, and more complete: the specification lists every operation a key can call — nearly 300 — with its parameters, body and response. Paste this URL into Postman, Insomnia, Swagger UI or an SDK generator — you do not have to copy the schemas by hand.
The document is served without authentication: a specification you need a key to read is a specification nobody evaluates before signing up. It only describes shapes — no workspace data passes through it.
Prompts for AI agents
Building the integration with Claude, Cursor, Copilot or another coding agent? These prompts give it the exact API contract so it does not have to guess. Copy, replace what is in angle brackets, paste.
Always start with the context sheet: it fits in a system message or at the top of a conversation, and every task prompt builds on it.
Context sheet — paste before any task
The facts the agent must know so it invents nothing: URL, authentication, error envelope, limits, where to read the full contract.
You will help me integrate the Iwana REST API (a booking SaaS for building-trade professionals, France/EU). Here is the contract; assume nothing that is not in it — read the OpenAPI specification first.
- OpenAPI specification (source of truth for every schema): https://iwana.fr/v3/api/v1/openapi.json
- Human documentation: https://iwana.fr/developers/api
- Base URL: https://iwana.fr/v3/api/v1/pro — every route below is relative to this prefix.
- Authentication: header "Authorization: Bearer <token>". Two token forms, same routes, same permissions:
- a workspace API key "iw_live_…", created in Settings → Developers; a test key "iw_test_…" reads the same real workspace and is refused every write (403 test_key_read_only, before the body is validated) — no separate demo workspace exists;
- an OAuth 2.0 access token "iwa_at_…" obtained through Authorization Code (authorize: https://iwana.fr/v3/oauth/authorize; token: POST https://iwana.fr/v3/api/v1/oauth/token as form-urlencoded; identity: GET https://iwana.fr/v3/api/v1/oauth/userinfo). Access token 1 h, refresh token 3 years and unchanged on refresh, PKCE S256 optional.
- No x-workspace-id header: the token carries the workspace.
- Health check: GET /integrations/me returns orgId, actor, permissions, locale, timezone.
- A key or a token opens the whole API in the specification (appointments, clients, sites, equipment, contracts, catalogue, team, quotes, invoices, interventions, projects, tasks, workflows, settings). A 403 means the user's role (OAuth token) or a test key (read-only) refuses the action. A key never calls the AI. A 402 erp_required means the workspace's plan lacks the ERP modules; a 403 offer_disabled means the offer is switched off for the whole platform.
- Errors: always { "error": { "code": "…", "message": "…", "requestId": "…" } }. "code" is stable, "message" is not: never branch on "message". X-Request-Id is present on every response.
- Limits: 600 requests/minute and 50,000/day per workspace, shared by all of its keys and tokens. Read X-RateLimit-Remaining and X-RateLimit-Remaining-Day; on 429, honour Retry-After (seconds). A 401/403 refused before the workspace budget is counted carries only the per-IP X-RateLimit-* headers, without the -Day ones.
- Retries: send an Idempotency-Key header (8 to 128 characters) on create POSTs (appointments, clients, contacts, companies, sites, equipment, contracts, quotes, invoices, payments, interventions, projects, tasks); the same key on the same route within 48 h returns the first response instead of creating a duplicate.
- Duplicates: POST /clients without an id always creates, it never matches on email or phone. Store the mapping between my IDs and Iwana's with PUT /external-refs { provider, entityType, localId, externalId } and resolve it with GET /external-refs?provider=&entityType=&externalId= before creating; without a match the answer is { "item": null } (200, not 404).
- Lists: each operation has its own page size and shape ({ items, total } with or without limit/offset, { items } or an array): read it in the specification, do not assume.
- Dates are ISO 8601 UTC; amounts named "…Cents" are cents. An undeclared field in a request body: 400 validation_failed, so send only the schema's fields. Unknown fields in a response: ignore them, never fail.
- Incoming webhooks: signed JSON POST; headers Iwana-Signature (sha256=<HMAC-SHA256 of the raw body>), Iwana-Event, Iwana-Delivery. Verify the signature on the RAW body, answer 2xx within 15 s, process asynchronously. A single delivery attempt with no automatic retry: plan a periodic reconciliation through the list endpoints.
- Never log a key, a client secret or a token.
The system I am connecting: <CRM / ERP / tool>.
1. Sync clients and appointments with an API key
A two-way, idempotent sync that respects the rate limits.
Using the Iwana context sheet above, implement a two-way sync between <my system> and Iwana with a workspace API key.
Requirements:
1. On start-up, call GET /integrations/me and stop with a clear message if the permissions do not include what the sync needs.
2. Read the catalogue (GET /catalog/services) and the team (GET /team) once and cache them to map my service and staff IDs.
3. For every contact in <my system>: first resolve GET /external-refs?provider=<my-provider>&entityType=client&externalId=<id>; if item is null, POST /clients (with an Idempotency-Key derived from my id) then PUT /external-refs; otherwise POST /clients with the Iwana id to update. Iwana does not match on email: never create the same contact twice.
4. Same pattern for appointments (POST /appointments with serviceId, clientId, startAt/endAt in ISO 8601 UTC, memberIds, customFields.<myId>, and an Idempotency-Key). On an update, always send startAt and endAt again.
5. Respect the budget: read X-RateLimit-Remaining, slow down when it drops below 10%, and on 429 wait Retry-After before retrying. Never retry a 400 or a 403.
6. Log the requestId of every error, never the key.
Start by listing the endpoints you will call and in what order, then implement.
2. Implement “Sign in with IWANA” (OAuth 2.0)
For a product several businesses install: the user authorises your app, you get a token per workspace.
Using the Iwana context sheet above, implement “Sign in with IWANA” (Authorization Code with a client secret, PKCE S256 enabled).
Contract:
- Redirect the user to https://iwana.fr/v3/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<URI registered, exact match>&response_type=code&state=<random>&code_challenge=<S256>&code_challenge_method=S256
- Back on redirect_uri: check state; if ?error=access_denied, show a message and exchange nothing. The code (iwa_ac_…) lives 60 s and works once.
- Exchange: POST https://iwana.fr/v3/api/v1/oauth/token, Content-Type application/x-www-form-urlencoded, grant_type=authorization_code&code=…&redirect_uri=<same value>&client_id=…&client_secret=…&code_verifier=…
Response: { access_token: "iwa_at_…", token_type: "Bearer", expires_in: 3600, refresh_token: "iwa_rt_…", scope: "…" }
- Identity: GET https://iwana.fr/v3/api/v1/oauth/userinfo with the bearer → { sub, email, name, org_id, org_name, role, scope }. Link my user account to the pair (sub, org_id).
- Refresh: grant_type=refresh_token&refresh_token=…&client_id=…&client_secret=… → new access_token, the refresh_token stays the same. Refresh on expiry (1 h), not per request.
- Token endpoint errors: { error, error_description } with invalid_request, invalid_client (401), invalid_grant, unsupported_grant_type. On invalid_grant during refresh, the grant was revoked or expired: mark the connection as needing re-authorisation and send the user back through authorize.
- A 401 invalid_token on an API route with a non-expired access token means the workspace revoked the app: same treatment.
- Keep access_token, refresh_token, expires_at, sub and org_id per connection; never log a token or the client secret.
Handle every case above: invalid state, access_denied, code expiry, token expiry and revocation.
3. Receive webhooks and verify the signature
An HTTPS endpoint that checks the HMAC on the raw body, answers fast and processes in the background.
Using the Iwana context sheet above, implement an Iwana webhook receiver.
Delivery contract:
- JSON POST to my HTTPS URL. Headers: Iwana-Signature: sha256=<hex HMAC-SHA256 of the raw body with my subscription secret>, Iwana-Event: <type>, Iwana-Delivery: <uuid unique per attempt>.
- Body: { "event": "appointment.created", "orgId": "…", "data": { "id": "…", "startAt": "…", "status": "…" }, "occurredAt": "…" }
- Events: the current list is x-iwana-webhook-events in https://iwana.fr/v3/api/v1/openapi.json (for example appointment.created, appointment.cancelled, client.updated); data always carries the record's id, with related ids, the status, ISO dates and amounts in cents.
- One attempt per event, 15 s timeout, no automatic retry: a missed event must be caught up by reconciliation.
Requirements:
1. Read the RAW body (before any JSON parsing) and compare the HMAC in constant time; answer 401 if the signature does not match.
2. Answer 2xx immediately after queuing the event; process asynchronously.
3. Process each Iwana-Delivery once (store processed IDs) as a precaution.
4. For every event, reload the full object with the matching GET (GET /appointments/{id}, GET /clients/{id}…) rather than trusting the partial payload; ignore event types you do not handle.
5. Never log the subscription secret.
6. Add a periodic reconciliation (GET /appointments?from=&to=, GET /clients) to catch up on missed events.
4. Build a client from the OpenAPI specification
Do not transcribe the schemas: the agent reads the public specification and builds the client from it.
Using the Iwana context sheet above, build a client for the Iwana PRO API from its OpenAPI specification.
1. Download https://iwana.fr/v3/api/v1/openapi.json and keep only the paths starting with /pro/: they are relative to the base URL https://iwana.fr/v3/api/v1 (the OAuth routes https://iwana.fr/v3/api/v1/oauth/token and https://iwana.fr/v3/api/v1/oauth/userinfo are not in it, they are described above).
2. Derive every request and response type from the specification rather than writing them by hand, so the client can be regenerated when the specification changes.
3. The client must: inject "Authorization: Bearer <token>", read X-RateLimit-Remaining and wait Retry-After on 429, turn the { error: { code, message, requestId } } envelope into a typed error carrying code and requestId, and ignore unknown fields.
4. Verify the client against the real API with GET /integrations/me using an iw_test_ key I provide.
Show me the list of retained operations first, then the client.
Ready to integrate?
Create your first key in the dashboard, or write to us to register an OAuth app.
We use cookies that are strictly necessary to run the service. With your consent we also switch on monitoring cookies (Sentry) to diagnose incidents. Read more in our cookie policy.