1Open the Connection tab
From the editor
In the 10-tab strip click 🔌 Connection. The tab body shows three groups: Base settings, Authentication, and Resilience (rate limiting, retries, circuit breaker). Use Esc to close any submodal that pops up here.
2Base URL & TLS
Set the base URL
The Base URL field (test id connection-base-url) is the root every command path is appended to. Examples:
https://graph.microsoft.com/v1.0https://my-tenant.service-now.com/api/nowhttps://impl-services.workday.com/ccx/service
Trailing slash optional. Use HTTPS for any production system.
TLS & timeouts
- Verify TLS — on by default. Turn off only for self-signed dev environments.
- Connect timeout — seconds to wait for the TCP handshake. Default 5s.
- Request timeout — seconds for the whole HTTP request. Default 30s.
3Authentication type
The Auth type dropdown (test id connection-auth-type) picks how EmpowerNow authenticates to the system. The form below the dropdown rebuilds based on your choice.
| Auth type | What you provide | Notes |
|---|---|---|
| None | Nothing | Public APIs only (rare). |
| API Key | Header name + key value | Static token in a custom header (e.g. X-API-Key). |
| Bearer Token | Token value | Sent as Authorization: Bearer …. Static — for short-lived tokens prefer OAuth. |
| Basic Auth | Username + password | Base64 encoded. |
| OAuth 2.0 (client credentials) | Token URL, client id, client secret, scopes | EmpowerNow fetches tokens automatically and refreshes when needed. |
| OAuth 2.0 (authorization code) | OAuth tab fully configured (see below) | For systems that need the end user's consent. |
| Custom (Headers) | List of header name/value pairs | Escape hatch for SaaS APIs that use proprietary auth. |
For any credential field, prefer the ${env:NAME} or ${secret:name} reference forms. The literal value never lives in the YAML; the platform resolves it from the secret store at runtime. Never commit raw API keys.
4Rate limiting and retries
Rate limiting
Toggle Rate limiting (test id connection-rate-limiting-toggle) on to throttle outbound calls. Two fields appear:
- Requests per second (
connection-rate-limiting-rps) — sustained rate. - Burst (
connection-rate-limiting-burst) — short-term spike allowance before the limiter throttles.
Match the upstream system's published limits to avoid 429s.
Retries & circuit breaker
The Retries section configures attempts on transient failures: max attempts, exponential backoff base, jitter. The Circuit breaker stops sending requests entirely after a configurable failure rate; useful when the upstream is reliably degraded.
5Test the connection
Click Test Connection
The Test Connection button at the bottom of the Connection tab (test id connection-test-button, aria-label "Test API") performs a sanity request against the base URL with the configured auth.
When it fails
Common errors:
| Symptom | Likely cause |
|---|---|
| DNS / connection refused | Wrong base URL, network ACL blocking the egress, or the system is down. |
| TLS handshake failed | Self-signed cert + Verify TLS is on — disable for dev or install the cert chain. |
| 401 / 403 | Bad credentials. Re-check secret references and OAuth client config. |
| 404 | Base URL is wrong (often a missing or extra path segment). |
| 429 | Throttled. Lower RPS in rate limiting. |
The system will save fine but every workflow that calls it will start failing. Always Test before Save when changing connection fields.
6OAuth tab — pick a preset
When to use OAuth
The OAuth tab is for systems that need an end user to consent to actions taken on their behalf — typically the authorization-code flow with PKCE. Set this up when:
- You're building a workflow that uses the user's own Slack / Google / Microsoft account.
- The platform delegates to the user's identity for read access.
For server-to-server (client credentials), configure OAuth directly on the Connection tab instead — you don't need this tab.
Choose a preset
Presets pre-fill the URLs and known scopes for the major identity providers. Pick Custom for anything not listed and provide the URLs yourself. The presets list has the test id oauth-presets; each entry has oauth-preset-<id>.
7Scopes, PKCE, and enrichment
Add scopes
The Scopes field (add via oauth-scope-add) is a list of OAuth scope strings the user is asked to consent to. Start narrow — only the scopes the workflow actually needs. Add more later as you wire up additional commands.
PKCE
Toggle Use PKCE on for any public client. The platform generates the code verifier and challenge automatically; no further config needed.
Token enrichment
Optional. The Enrichment section can call a follow-up endpoint after the token exchange (e.g. userinfo) and merge the response into the user's identity for downstream use.
UI branding
Set Display name (test id oauth-display-name), button colour, and icon. These appear on the consent screen the end user sees.
8Delegation broker
When a workflow or AI agent acts on behalf of an end user, the Delegation Broker issues a constrained token. The Delegation tab configures the broker for this system.
| Field | What it does |
|---|---|
| Enable delegation | Master toggle. When off, every command runs as the platform service account. |
| Allowed scopes | Subset of the system's OAuth scopes that delegation may request. Anything outside is rejected. |
| Capabilities | Functional caps the delegated principal can use: read, write, list, delete. The Designer's per-command MCP config can refine further. |
| Response filter | Field-level redaction applied to delegated responses (e.g. mask ssn). |
| Error filter | Sanitises error messages before they leave the platform — prevents leaking internal IDs to the delegate. |
If you expose commands as MCP tools and want AI agents to call them with end-user identity, fill in this tab. Otherwise the broker is bypassed.
9Automation: webhook ingress
The 🤖 Automation tab configures how the external system pushes events back to EmpowerNow. Two modes are common: webhook (system calls EmpowerNow when something happens) and poller (EmpowerNow polls the system on a schedule).
Enable automation
Toggle Enable automation (test id automation-enable-toggle) on. Choose an Event family (test id automation-event-family) — e.g. identity.lifecycle, access.changes, incidents.created. The family scopes the events this ingress publishes.
Webhook mode
Pick Webhook in the Mode toggle (test id automation-mode-webhook). Configure:
| Field | data-testid | Notes |
|---|---|---|
| Webhook endpoint | automation-webhook-endpoint | The path the platform exposes (e.g. /webhook/entraid). Provide this URL to the upstream system. |
| Webhook secret | automation-webhook-secret | Shared secret. Reference an env var or secret store entry. |
| Signature header | automation-webhook-sig-header | HTTP header name where the upstream system places the signature (e.g. X-Slack-Signature). |
| Signature algorithm | automation-webhook-sig-algorithm | Algorithm used to compute the signature (e.g. HMAC-SHA256). |
| Subject template | automation-subject-template | Templated NATS-style subject the event is published to: e.g. identity.{{ payload.userId }}. |
10Automation: poller mode
When to use polling
Pick Poller (automation-mode-poller) when the upstream doesn't expose webhooks. EmpowerNow runs a recurring command and emits an event for each new record.
| Field | data-testid | Notes |
|---|---|---|
| Interval | automation-poller-interval | How often to poll (seconds or cron expression). |
| Command ref | automation-poller-command-ref | Name of the command to call on each tick. Must exist in the Designer. |
| State key | automation-poller-state-key | Field on each result used as a watermark (e.g. updated_at). The poller keeps a "last seen" value to avoid double-emits. |
| Timestamp | automation-poller-timestamp | ISO timestamp field that anchors the poll window. |
Hybrid mode
Some systems support both: a webhook for the most common events plus a polling sweep to catch anything missed. Pick Hybrid in the Mode toggle and configure both blocks. The platform deduplicates by the state key.
After saving, watch the platform-ops dashboards or the system's mind-map node detail to confirm events are flowing. Webhooks: send a synthetic event from the upstream. Pollers: wait one interval and check the last-seen state key.