Integration walkthrough

Nine steps. Each one links the reference page that owns the detail, and ends with the thing that most often goes wrong there.

This is the first decision and the hardest one to reverse, because the allowed-origins list means the opposite thing in each shape.

Browser-direct is the widget calling agentifys.ai from the page. The project key is in your HTML for anyone to copy, and the allowed-origins list is the only thing that limits where that copy can be used. Fill it in with every origin you serve from.

Server proxy is what we are building. The browser only ever talks to app.acme.com, and Acme's server is the only holder of the project key. Those forwarded requests carry no Origin header at all, and an absent origin is read as the empty string, which never matches a non-empty list. So the allowed-origins list must stay empty: one entry refuses every call the proxy makes.

What replaces the allowlist in this shape is your own perimeter. The proxy route sits behind the session check your app already performs, so an unauthenticated visitor cannot reach Agentifys through it at all.

The exact matching rules — scheme, host and port, no wildcards, no subdomains — and the list of routes the check runs on are in the API overview.

The widget derives every request path from one base. Point it at your server with data-base-url and it will call /era/v1/chat, /era/v1/history, /era/v1/project-config and the rest on your host.

<script>
  // The proxy decides who this is. The id here only tells the widget that someone
  // is signed in, so it asks for the per-user features at boot.
  window.ERAConfig = { user: { id: "u_42" } }
</script>
<script
  src="https://agentifys.ai/static/widget.js"
  data-base-url="https://app.acme.com/era"
  data-api-key="era_placeholder"
  data-title="Acme Assistant"
></script>

Chat is the route that needs care. The response is always text/event-stream and it must be written through chunk by chunk.

// server.js — Node 18+, Express. Every Agentifys call the browser makes goes here.
const ERA    = "https://agentifys.ai"
const KEY    = process.env.ERA_PROJECT_KEY      // era_...  never sent to the browser
const SECRET = process.env.ERA_SIGNING_SECRET   //          never sent to the browser

// Your own session is the ONLY source of identity. Whatever the page sent is discarded.
// signUserContext is the signer from the Identify users guide.
function identityFor(req) {
  return signUserContext(
    { id: req.session.userId, name: req.session.name, role: req.session.role },
    SECRET,
  )
}

app.post("/era/v1/chat", express.json(), async (req, res) => {
  const upstream = await fetch(ERA + "/v1/chat", {
    method: "POST",
    headers: { Authorization: "Bearer " + KEY, "Content-Type": "application/json" },
    // message, session_id and client_tz pass through. The identity does not.
    body: JSON.stringify({ ...req.body, user_context: identityFor(req) }),
  })

  res.status(upstream.status)
  res.setHeader("Content-Type", upstream.headers.get("content-type") || "application/json")
  res.setHeader("Cache-Control", "no-cache")
  res.setHeader("X-Accel-Buffering", "no")
  res.flushHeaders()
  // Write each chunk through as it arrives. Collecting the body first turns a
  // streaming reply into a long pause followed by a wall of text.
  for await (const chunk of upstream.body) res.write(chunk)
  res.end()
})

In the console, under Settings then Identity, switch the project from open to signed. The signing secret is minted for you the first time that switch is saved; there is no separate generate step. Copy it into the proxy's environment next to the project key. Those two values are the whole set of things that must never reach a browser.

Signed identity is not optional for this integration. The vault, per-user private documents, per-user MCP OAuth and every scheduling route refuse an open-mode project outright with SIGNED_IDENTITY_REQUIRED.

The signature is an HMAC-SHA256 over a canonical JSON of the identity plus a Unix timestamp _ts, and it is valid for 300 seconds. The recipe, including the non-ASCII escaping that an Arabic or emoji-bearing name depends on, is in Identify users. Use it as written.

Now that the proxy substitutes the identity rather than passing it through, it has to know where each route carries it. The location is not guessable from the HTTP method, and there is no fallback: a route reads exactly one place, and an identity sent anywhere else is treated as absent.

These are the routes this integration touches. The widget calls every one of them except the vault, which only your backend calls.

Always URL-encode the X-Era-User value. A raw JSON header is accepted, but a name containing a non-Latin-1 character is rejected by the browser before the request leaves — and a signature over a name you had to strip is a signature that will not verify. The full matrix, every route included, is on the API overview.

A tool is an HTTPS endpoint you already own. Register lookup_order against Acme's own API, describe it for the model, and give it a JSON schema for its arguments. The model's arguments arrive nested under input, so your handler reads body.input.order_id, and the caller's profile arrives alongside as body.user.

{
  "name": "lookup_order",
  "display_name": "Look up an order",
  "description": "Look up the status of one of this customer's orders by its id.",
  "enabled": true,
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  },

  "executor_type": "webhook",
  "webhook_url": "https://api.acme.com/orders/lookup",
  "webhook_method": "POST",
  "webhook_headers": { "X-Api-Key": "{{user.creds.acme_api_key}}" },

  "requires_confirmation": false
}

Return application/json with a 2xx. Signal a business-level failure — no such order — as a 200 with an error field in the body, not as a 404: a 4xx never reaches the agent, it becomes TOOL_UNAVAILABLE and your response body is discarded. The request and response shapes, the retry and idempotency contract, and the SSRF rules that apply to every webhook URL are in Connect tools.

issue_refund is the same shape with one field changed. Setting requires_confirmation to true is what makes it a write as far as the platform is concerned, and that single flag governs two separate gates: the in-chat approval now, and what a scheduled run is allowed to touch later.

{
  "name": "issue_refund",
  "display_name": "Issue refund",
  "description": "Refund one of this customer's orders. Confirm the amount first.",
  "enabled": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string" },
      "amount":   { "type": "string" }
    },
    "required": ["order_id", "amount"]
  },

  "executor_type": "webhook",
  "webhook_url": "https://api.acme.com/orders/refund",
  "webhook_method": "POST",
  "webhook_headers": { "X-Api-Key": "{{user.creds.acme_api_key}}" },

  "requires_confirmation": true
}

When the model calls it, nothing runs. Agentifys holds the call against the session, emits a confirmation_required event carrying the display_name, the exact input, and the two literal tokens that resolve it, and ends the turn. The embedded widget draws Approve and Cancel for you. If you render your own transcript, you send the token back as the next user message on the same session_id.

// The event that ends the turn. Read confirm/decline off it; do not hardcode them.
{
  "type": "confirmation_required",
  "id": "toolu_01B4",
  "name": "issue_refund",
  "display_name": "Issue refund",
  "input": { "order_id": "1043", "amount": "42.00" },
  "confirm": "__era_confirm__",
  "decline": "__era_decline__"
}

Everything the stream can emit, in what order, and what each resume produces is on the chat reference.

Both tools authenticate as the customer, not as Acme, so the key cannot live in a static header. Store it once per user in the vault and reference it by name. The write is server to server: your backend sends the signed identity, the name and the value.

// Your own settings page: the customer pastes their Acme API key into your UI,
// your backend puts it in the vault. The browser never touches /v1/credentials.
app.post("/settings/acme-key", express.json(), async (req, res) => {
  const r = await fetch(ERA + "/v1/credentials", {
    method: "PUT",
    headers: { Authorization: "Bearer " + KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      user_context: identityFor(req),
      name:  "acme_api_key",       // the exact name you reference in the tool header
      value: req.body.apiKey,
    }),
  })
  // The response is a masked hint, never the value: { name, secret_hint }.
  res.status(r.status).json(await r.json())
})

All three credential methods skip the origin check, because they are designed to be called from a server that sends no Origin header. They still require signed identity, which is what binds the secret to a verified user rather than to a claim. Names, size limits, the per-user cap and the write throttle are in the vault guide.

Once it is stored, {{user.creds.acme_api_key}} in the tool's webhook_headers resolves to the decrypted value at call time. The substitution happens after the model has chosen to call the tool, so the secret is placed in the outbound request and never enters the prompt or the transcript. Templating resolves in webhook_headers and webhook_params only — not in webhook_url, and not in the arguments the model produced.

In Settings, under Scheduling, enable it. Four reserved tools become available to the model — schedule_task, list_scheduled_tasks, update_scheduled_task and cancel_scheduled_task — and the customer schedules by asking, not by filling in a form.

"Every Friday at 5pm, summarise my open orders and flag anything
 that has been stuck for more than a week."

That much gets you a run that can read, summarise and report. It cannot refund anything, and this is the second switch people miss. A scheduled run may only use a write tool that was pre-authorised on that task, and the pool it can be drawn from is the project's Tools allowed to run unattended list, which starts empty. Tick issue_refund there first; only then can the agent attach it to an individual task.

What a run carries, how the timezone is resolved, the five ways a run ends, and the My-tasks panel are in the scheduling guide.

Each of these fails quietly rather than loudly, which is why they are worth doing deliberately rather than waiting to notice.