Connections and credentials

Connections supply the configuration that a workflow route would need to reach an external app. Credentials are one part of that connection model, but their presence does not guarantee that a connector is executable. Use this guide to interpret connection states, address missing setup, and keep secrets outside workflow descriptions while the storage and retention contract remains under review.

Connection model

Workflow Agent can reason about an app relationship before a connection exists. The draft layer identifies apps and possible routes; the connection layer records whether the environment has enough configuration to attempt that route. A bridge, native connector, generated connector, HTTP path, webhook concept, or MCP definition can each have a different connection model.

The integrations surface groups several categories:

• credentials associated with apps or providers;
• bridge-provider configuration;
• generated connectors that may still require review;
• native connectors represented by the current data source;
• MCP servers shown in configuration or dry-run form;
• webhook and API-route concepts whose live behavior is not verified.

Connection status should be read with route status and execution state. configured means configuration data is present. needs-setup indicates a missing requirement. expired means the current credential cannot be relied upon. config-preview, dry-run, live-blocked, and disabled all stop short of live execution.

A connection does not change the product’s preview boundary. Workflow Agent still keeps activation locked, and generated connector review cards keep canExecute=false where specified.

Add a connection

Open the canonical integrations route and choose the area that matches the draft’s proposed execution route. The exact labels can change, so begin from the missing requirement shown in the builder rather than guessing which provider or connector should be used.

Before entering any credential, confirm:

1. the app in the connection matches the detected app in the draft;
2. the route mechanism is the one shown by route readiness;
3. the configuration is intended for the current environment;
4. the secret has the minimum permissions required for the proposed action;
5. the integration is not marked preview-only, live-blocked, or disabled.

The supplied sources verify the existence of credential and connection stores, but they do not establish every user-facing creation control or provider flow. If the interface presents only a configuration preview, save or inspect only what that preview supports. Do not interpret a sample account name, seeded value, or bridge card as an active connection.

After configuration, return to the draft and rerun validation. A useful result is a change from a missing-credential warning to a more specific route or simulation state. It is not evidence that an external app accepted a request.

Credential handling

Keep provider secrets out of natural-language prompts, step inputs, read-only workflow JSON, screenshots, and support messages. Credentials belong in the connection layer, where the product can reference them without embedding the raw value in the workflow definition.

The current source bundle does not verify a complete security contract for encryption, key management, tenant isolation, deletion, provider-side storage, or retention. Documentation therefore must not promise that a credential is encrypted in a particular way or removed after a fixed period. Privacy and service responsibilities are governed by the currently approved Privacy and Terms pages, while the implementation details remain subject to security review.

A credential can still be evaluated operationally without making unsupported storage claims. Check whether it is present, whether its state is current, whether the related route allows a dry run, and whether policy or approval gates remain. Treat any value rendered in seed data as illustrative rather than as a real secret.

Missing credentials

A missing credential should appear as a setup problem, not as a generic workflow failure. The draft may remain valid, but the affected route cannot progress to the same readiness level as a configured path.

Work backward from the blocked step:

• identify the app and action;
• note the proposed execution route;
• locate the matching connection category;
• confirm whether the route requires an app credential, bridge configuration, or another form of setup;
• rerun draft validation after the missing item is addressed.

If no supported connection control exists, leave the requirement unresolved. Do not paste a token into a text field or invent a provider setup route. A simulation can still be valuable when it explicitly reports that the action would stop for missing credentials.

An expired credential is different from an absent one. Replace the expired value through the available connection workflow, then revalidate. If the status remains unchanged, the problem may be provider configuration, route readiness, or a non-executable connector rather than the secret itself.

Rotation

No dedicated Rotate button or universal rotation API is verified. Use a conservative replace-and-revalidate pattern instead of documenting a control that may not exist.

Prepare a new provider credential with the required scope, add it through the supported connection area, and keep the old credential active until the new configuration can be inspected. Update the connection reference if the interface supports that operation. Run draft validation and a no-write simulation, then revoke the old provider credential through the provider’s own supported process when the replacement is confirmed.

This sequence reduces the chance of breaking a route, but it does not prove zero downtime or provider acceptance. Avoid claiming that Workflow Agent automatically migrates in-flight work, because live execution and production runs are not part of the verified product state. Record the date and connection affected in your organization’s own operational notes; avoid recording the raw secret.

Troubleshooting

If a credential appears configured but the builder still reports it missing, compare the app identity and route mechanism rather than repeatedly re-entering the secret. A connection may be associated with a different app, environment, or connector. When the source data, connection store, and builder disagree, preserve the blocked state and request a security or implementation review.

Separate identity, secret, and route

A connection can combine several ideas that should remain distinct. The app or provider identity says which external system the workflow intends to reach. The credential proves authority to that system. The route determines how Workflow Agent would use the connection. A credential stored for one route does not automatically enable another.

This distinction explains why a builder can continue to report missing setup after a secret has been added. The connection may target another account, app, provider, or bridge. Compare identifiers and route type without exposing the raw value.

Expiration and revocation

An expired credential should stop the dependent route. A revoked credential can look configured locally while failing when a provider is eventually contacted. Since live execution is not verified, the preview may not be able to distinguish those conditions through a remote check. Keep the state conservative and update the connection through the supported interface.

Provider-side revocation is outside the Workflow Agent source bundle. Do not claim that removing a local connection revokes the provider token or deletes provider data. Coordinate both sides of the change through their supported controls.

Administrative review points

An administrator reviewing a connection should know which workflow drafts reference it, what app and route it serves, whether it is current, and which approval or policy gates apply. The present sources do not verify a complete dependency report, so this information may require manual comparison between builder and integrations views. Record references without copying secrets into notes.

Connection scope

Use the narrowest connection scope that can support the draft’s proposed action. Connection-store evidence does not publish a universal permission matrix, so do not name exact scopes unless the current provider or interface shows them. The review should still ask whether the credential can read, create, update, or administer more data than the workflow needs.

A broad credential can increase the impact of an error even while live execution is disabled. Recording the intended minimum access now makes a future security review more precise.

Multiple environments

Connections can differ between development, test, and production-like environments. A configured status in one environment should not be copied into another draft as proof of readiness. Keep app identity, account identity, route, and environment associated with the connection reference.

Failed replacement

If a replacement credential does not clear the missing or expired state, restore the previous valid reference where supported and keep the route blocked. Do not delete the old provider credential until the new configuration is confirmed. Since no live workflow runs are verified, the main risk is losing a reviewable setup rather than interrupting a production execution, but provider-side access still requires careful handling.

Auditability boundary

The current source set does not prove a complete credential audit log. Document the connection state and date of review without claiming that every creation, view, replacement, or deletion is recorded by Workflow Agent. Avoid writing the secret into an external ticket to compensate for missing audit detail.

Connection review after draft changes

Changing the source app, destination app, action, or execution route can invalidate an earlier connection choice. Reopen integrations after major draft edits and compare the connection identity with the new step. A credential that was appropriate for one action may be unnecessarily broad or entirely unrelated to another.

Data-minimization principle

Store only the configuration needed to identify and use the connection. Do not copy raw secrets into workflow notes, screenshots, example JSON, or simulation evidence. The absence of a complete retention contract makes minimization especially important during preview.

Removing a connection

No universal removal or cascading-revocation procedure is verified. If a supported control removes a local connection, do not state that it also revokes the provider credential or deletes provider-side data. Keep affected drafts blocked until their route and credential references are reviewed again.

Connection naming

Use a descriptive connection name that identifies the app and environment without embedding the secret or account-sensitive data.