Embedding connection settings

Give your customers a settings screen for their integration inside your own product, without building one. You design one or more forms in the dashboard. Each customer fills them in for their own connection, in an iframe on your page, and your backend reads their answers through the Management API.

Use it for the choices your integration needs from each customer: which sites to sync, a default cost center, whether to create work orders automatically. Use several forms when different screens of your product ask different questions, for example sync options in one place and routing rules in another.

What your customer sees

The embed shows the connection's platform and status, your form, and a save button. Your customer can also:

Switch the integration on and off with Activate and Deactivate.

Disconnect the integration, which removes the connection.

The form checks required fields and formats such as email, URL and phone, and shows or hides fields based on other answers.

Set it up

Design the form

Open Settings → Embedded Experience → Forms in the dashboard and create a form. Each form has a name and a form key, which you pass when you create a session. Your first form is the default; you can make another form the default later. Build each form from groups (each group is a card on the form) and fields:

Field types: text, long text, dropdown, multi-select, toggle, radio, number and date.

Mark fields as required, and add descriptions.

Show a field or group only when other answers match your conditions.

Add a one-time warning that appears when an answer matches a condition.

The preview shows exactly what your customers will see. Each group and field has a key: that's the name its answer is stored under, and it never changes, even if you rename the label.

Create an embed session on your backend

When your customer opens the settings page in your product, your backend asks Makini for a session for one form. Use a client_credentials token with the connections:read scope (see Access tokens):

Leave out the body, or form, to open your default form. A form key that doesn't exist answers 404.

{
  "session": {
    "token": "q4X…",
    "url": "https://embed.makini.io/embed/q4X…",
    "expiresAt": "2026-09-25T11:00:00.000Z"
  }
}

A session lasts one hour. Create a new one each time the page loads. The connection must have credentials; a connection that hasn't been connected yet answers 409.

Create sessions on your server only. Never put your client secret or Management API token in the browser.

Embed the iframe

Pass session.url to your page and load it in an iframe:

The session URL is the only credential the page needs. It's scoped to one connection and one form.

Listen for events

The embed posts messages to your page with window.postMessage. Each message is an object with an event field and the payload below.

`event`	When	Payload
`makini:ready`	The form has loaded.	None
`makini:error`	The embed can't show the form.	`code`, `message`
`makini:settings.updated`	Your customer saved the form.	`connectionId`, `form` (the form key)
`makini:connection.deleted`	Your customer disconnected the integration.	`connectionId`

makini:error codes:

`code`	Meaning	What to do
`SESSION_EXPIRED`	The session is older than one hour.	Create a new session and reload the iframe.
`CONNECTION_DEACTIVATED`	The connection is switched off.	Show your own message, or reactivate the connection.
`LOAD_ERROR`	The session isn't valid, or the page couldn't load.	Create a new session and retry.

Check event.source so you only handle messages from your own iframe.

Read the saved settings

Your backend reads a connection's answers to one form with the same connections:read token. Each form's answers are kept separately:

{
  "connectionSettings": {
    "settings": {
      "sync": { "sites": ["north", "south"], "create_work_orders": true },
      "defaults": { "cost_center": "CC-4100" }
    },
    "formEnabled": true,
    "formConfigVersion": 3,
    "updatedAt": "2026-09-25T09:41:12.000Z"
  }
}

Leave out form to read your default form.

settings is keyed by group key, then field key.

A field-selection answer is { "entity", "table", "fields" }. table is a raw table you can read at /v4/raw/tables/<table>. fields lists the chosen fields in your customer's order, each as a path: the column, then the keys inside it when the column holds JSON. A * segment stands for each item of a list. For example: [["status"], ["attributes", "color"], ["client", "versionedObjects", "*", "id"]].

formEnabled is what Activate and Deactivate set, kept per form. While it's off, settings is {}, so nothing downstream acts on the old answers. The answers are kept and come back when your customer switches it on again.

updatedAt is null until your customer saves for the first time.

Your customer's whole embedded experience

With Customers on your plan, one session can open everything for one of your customers: the systems they have connected, a Connect a system button that runs Makini Link for them, and each connection's settings forms. Your backend names the customer by your own ID for them; Makini creates the customer the first time it sees the ID. Use a client_credentials token with connections:write:

The answer has the same shape as a single-connection session; load session.url in the same iframe.

Field	Does
`endCustomer.externalId`	Your ID for the customer. Connections they make carry it in their metadata under your customer ID field, so they appear on that customer.
`open`	Where the session opens: `home`, `connect` (with an optional `platform`), `connection` (with `connectionId`) or `form` (with `connectionId` and `form`).
`enable`	Forms, solutions and flow folders to turn on for a connection made in this session, by name.
`returnUrl`	Where Makini Link sends your customer after they connect. It must be one of your registered redirect URIs; leave it out to return to the embed.

The session lasts an hour from its last use, and eight hours at most. On Settings → Embedded Experience → Customers, the settings beside the list choose what your customers can do (connect, reconnect, disconnect, contact support). To see what a customer sees, choose Open as customer on their row, or Copy link to send it.

Choose what each connection has

Each form, solution and flow folder is a feature of a connection. On Settings → Embedded Experience → Features, decide for each one:

Offered on: every system, chosen systems, or only the connections you turn it on for.

Turns on: by itself when a connection is made, or when your customer chooses it.

A connection's own features are under Features in its menu on the Connections page. From your backend, name features when you create a connection or start Makini Link:

GET /connections/{id}/features lists them with what turned each one on, and PUT /connections/{id}/features sets exactly which are on.

Manage forms from your backend

Forms are also on the Management API, so you can keep them in your own repository and publish them with your releases. Use a client_credentials token; reading forms needs clients:read and changing them needs clients:write.

PUT creates the form when the key is new and replaces it otherwise. Makini keeps the form's version, which rises with every save. Add "isDefault": true to make it your default form, or "key" to rename it.

Route	Does
`GET /embed/forms`	Lists your forms, the default first.
`GET /embed/forms/{key}`	Reads one form with its groups and fields.
`PUT /embed/forms/{key}`	Creates or replaces a form.
`DELETE /embed/forms/{key}`	Deletes a form and your customers' answers to it. Make another form the default before deleting the default one.

Styling

To match your product, Settings → Embedded Experience → Appearance (a plan add-on) brands the embed like Makini Link: your colors, a corner radius and a font. The bar above the page shows the wide logo from Settings → Application.

Embedding connection settings

What your customer sees#

Set it up#

Your customer's whole embedded experience#

Choose what each connection has#

Manage forms from your backend#

Styling#

What your customer sees

Set it up

Your customer's whole embedded experience

Choose what each connection has

Manage forms from your backend

Styling