Runtime Connection Overrides

A workflow never contains credentials — each node references a Connection by ID, and the platform resolves the actual credentials when the App runs. That resolution step is also where overrides happen: a node bound to a requirement instead of a concrete Connection is resolved per request, using the connection the calling end user linked. This page explains the resolution model, how to override per user, and what is deliberately not overridable.

How connections resolve at run time

1. Build time — a node's connection field stores either a Connection ID or a requirement reference. The workflow definition (and every saved version) carries only these references, never secrets.
2. Deploy — deploying packages the workflow for the App's runtime. Connection references travel with it.
3. Run — the execution engine resolves credentials through an internal, system-authenticated credentials API. The request carries the referenced Connection IDs plus — when the run has one — the App ID and the run's user_id, so the platform can substitute end-user connections for requirement-bound nodes.

Because secrets live only in the Connections store and resolution is server-side, reading a workflow or its versions back through the API never exposes credentials, and the same workflow version can serve different credentials to different callers.

Per-user overrides with requirements

The override mechanism at invoke time is the end-user connection requirement. Instead of selecting a concrete Connection on a node, the builder selects a requirement; each end user then links their own connection for that requirement, once per App.

At run time the platform looks up the connection linked for the triple (App, user_id, requirement) and the node runs with that user's credentials. Only connections in status active count — an unauthorized or expired link leaves the requirement unsatisfied, which you can detect before running:

# Which requirements has this user satisfied?
curl "https://<your-app-hostname>/v1/requirements/status?user_id=user-42" \
  -H "Authorization: Bearer $DYNAMIQ_ACCESS_KEY"

The override is keyed by the user_id you send with the run, so pass it on every request:

curl -X POST "https://<your-app-hostname>/v1/runs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DYNAMIQ_ACCESS_KEY" \
  -d '{
    "input": { "question": "Summarize my latest invoices" },
    "user_id": "user-42"
  }'

import os

import requests

endpoint = "https://<your-app-hostname>"
headers = {"Authorization": f"Bearer {os.environ['DYNAMIQ_ACCESS_KEY']}"}

run = requests.post(
    f"{endpoint}/v1/runs",
    headers=headers,
    json={
        "input": {"question": "Summarize my latest invoices"},
        "user_id": "user-42",
    },
).json()

print(run["status"], run.get("output"))

Two requests that differ only in user_id run the same workflow version against different accounts — that's the runtime override in action. The full lifecycle (defining requirements, the hosted connect page, the connect API) is on End-User Connection Requirements.

What you can't override per request

There is no connections field in the invoke payload. The direct invoke endpoint (POST https://<your-app-hostname>) accepts exactly these top-level fields — and POST /v1/runs swaps execution_mode/callbacks for user_id, session_id, and background. Neither carries a connection override:

So if you need different credentials, pick the mechanism that matches the scope of the change:

Next steps