How Connectors Work

A connector is a server-side proxy that sits between your widget and an external API. Every connector request passes through a pipeline of processing stages before reaching the destination, and the response passes through its own pipeline before returning to your widget.

The pipeline

Request pipeline

Each stage runs in order before the HTTP request leaves the platform.

Merge Params & Headers — The platform combines the connector's configured headers and query parameters with any overrides sent from the widget code. Fields marked as non-overridable cannot be changed by the browser. See Headers & Query Parameters.

Resolve Template Variables — Template expressions like {{ user.id }} and {{ tenant_id }} are replaced with values from the authenticated session. These values are resolved on the server — the browser cannot see or tamper with them. See Template Variables and Passing User Context.

Inject Secrets — Expressions like {{ get_secret('api_key') }} in headers, query parameters, and authentication fields are replaced with encrypted secret values. Secrets are never exposed to the browser. See Secrets.

Apply Authentication — The platform applies the configured authentication method — adding an API key header, exchanging OAuth credentials for a token, or signing a JWT. See Authentication.

Request Payload Transformation — If a request transformation is configured, the request body is transformed before sending. This lets you reshape data from the widget into the format the external API expects. See Request Transformation.

Cache Lookup — For GET and HEAD requests, the platform checks whether a cached response exists before calling the external API. On a cache hit, the cached response is returned directly — the external API is never called. On a cache miss, the request proceeds to the external API and the response is stored for future requests. See HTTP Caching.

Response pipeline

After the external API responds (on a cache miss), the response passes through one stage before returning to the widget.

Response Payload Transformation — If a response template is configured, the response body is transformed before returning to the widget. This lets you filter, reshape, or reformat the API's response. See Response Transformation.

Where data belongs

Different types of data enter the pipeline at different points. Use this decision tree to determine where a value should be configured.

The rule is: if the external API uses a value to decide who is making the request or what they are allowed to do, that value must come from the server, not the browser.

See Secrets for credential storage, Passing User Context for user identity fields, and Calling from Widget Code for SDK parameters.

Next Steps

• Build Your First Connector — Hands-on tutorial to create and call a connector
• Passing User Context — Securely inject user identity into requests
• Template Variables — Full reference of variables, filters, and functions