Connections & OAuth2
Connections define how a workflow authenticates with an external service — API keys, OAuth2 clients, basic auth — so nodes never carry credentials in the workflow graph. Connections (and their API keys and OAuth2 tokens) are defined and stored in WP-PFManagement; WP-PFWorkflow reads each connection Management-first and executes with it. See OAuth outbound for the node and OAuth Client for the connection config.
Why centralised connections
- Security: credentials are stored in Management's encrypted field, never in the workflow JSON; the REST surface returns only a masked preview.
- Auditability: every connection use is logged in the audit trail.
- Reusability: one connection serves many workflows.
- Capability-gated: managing connections is gated in Management; a workflow author uses a connection without ever seeing its secret.
Connection types
| Type | How it authenticates | Example services |
|---|---|---|
| API Key | Static token or key in header | OpenAI, Anthropic, DeepSeek, Slack, Stripe |
| OAuth2 | Authorisation code + client credentials, with refresh | Google, Microsoft 365, Salesforce, GitHub |
| Basic Auth | Username + password | Legacy APIs |
| Bearer Token | Pre-generated token | wp-executor remote workers |
OAuth2 flow (tokens live in Management)
- Define the OAuth Client connection in WP-PFManagement (client ID/secret, endpoints, scopes).
- Start the authorization from that connection; the provider redirects back to
GET /wp-json/wp-pfworkflow/v1/oauth/callback?state=...&code=...— WP-PFWorkflow runs the flow. - Token exchange: the engine exchanges the code for access + refresh tokens.
- Storage: the tokens are written back to Management, the single store for OAuth tokens. WP-PFWorkflow keeps no local token copy; it reads the decrypted token in-process only for the moment it makes the call.
The same engine also runs the client_credentials grant (machine-to-machine, no user) and refreshes expired access tokens automatically. Every token-endpoint call goes through the outbound SSRF guard.
Using connections in nodes
Nodes that talk to an external service expose a "Connection" selector in their configuration. Pick a connection defined in Management instead of entering credentials; the node authenticates with it on every execution.
Testing connections
Use the connections.test_connection node in a workflow. A successful test verifies:
- Credentials are valid
- The service is reachable
- The account has the expected permissions
Rotation and expiry
- API keys: rotate by updating the connection in Management; the new value takes effect immediately.
- OAuth2: refresh tokens are used automatically when the access token expires. If refresh fails, the connection needs re-authorization and nodes fail with a clear error message.