Learn how to configure a Pipeline Secret that automatically renews itself before it expires, so pipelines calling external services with short-lived OAuth (Open Authorization) tokens never fail due to an outdated credential.
Prerequisites & Permissions
Before configuring an auto-refreshing secret, ensure you have the required access and configurations:
Plans: Available wherever Pipelines and Pipeline Secrets are enabled.
Role & Permission: Requires Account Admin permissions. The Pipelines page (Settings > Automation Settings > Pipelines) is restricted to Account Admins.
Dependencies: The external service must expose an authentication endpoint (for example, an OAuth token endpoint) that returns a fresh token given a client ID and/or client secret.
NOTE: Existing **Static** secrets are unaffected by this feature and continue to work exactly as before. Auto-refresh is opt-in per secret.
Key Concepts
Term | Description |
Static Secret | The original secret behavior: a fixed value you paste in once and update manually whenever it changes or expires. |
Auto-Refresh (Refreshable Secret) | A secret backed by an authentication endpoint. Before each pipeline run that uses it, wxrks checks whether the stored token is expired (or close to it) and, if so, calls the endpoint to fetch a new one automatically. |
Expiry Buffer | The number of seconds before the token's real expiration that wxrks proactively refreshes it, avoiding a request that fails because the token expired mid-flight. |
Failing Status | The state a refreshable secret enters when a refresh attempt errors out (bad credentials, unreachable endpoint, unexpected response shape, etc.). |
Step-by-Step Instructions
Step 1: Open Pipeline Secrets
Log in to wxrks as an Account Admin.
From the main navigation, go to Settings > Automation Settings > Pipelines.
Click the Secrets tab.
The secrets table lists every existing secret with a Type column showing either a Static or Refreshable badge, so you can tell at a glance which secrets are self-renewing.
Step 2: Create or Edit a Secret
Click Create Secret (or the Edit icon on an existing secret) to open the secret modal.
Enter the Secret Name (uppercase letters, numbers, and underscores only) and the Secret Value.
NOTE: For a new refreshable secret, the **Secret Value** field can hold a placeholder or an initial token — the first refresh overwrites it automatically. wxrks never displays a saved secret value again, whether static or refreshable: reopening any secret to edit it always shows the **Secret Value** field empty, and you must re-enter a value to save changes. The **Secret Name** itself can't be changed once created, since pipelines reference it by name.
Enable Auto-refresh this token to reveal the refresh configuration panel.
Step 3: Configure the Refresh Request
Fill in how wxrks should call the external authentication endpoint:
Auth Endpoint URL: The full URL wxrks calls to request a new token.
HTTP Method:
POST,GET, orPUT, depending on what the provider expects.Client ID: Optional identifier sent to the provider, if it requires one.
Client Secret: The credential used to authenticate the refresh request itself.
Request Body Template: Optional JSON (JavaScript Object Notation) body sent with the request. Reference
${{ '{\{' }} refresh.clientId }}and${{ '{\{' }} refresh.clientSecret }}as placeholders for the values above.
For example, a provider expecting a JSON body with the client credentials would use:
{"client_id": "${{ '{\{' }} refresh.clientId }}", "client_secret": "${{ '{\{' }} refresh.clientSecret }}"}
NOTE: The **Client Secret** field is write-only: once saved, it is never returned by the API or shown in the form again. When editing a refreshable secret, leave it blank to keep the previously saved value — it is only overwritten if you type a new one.
Step 4: Tell wxrks Where to Find the New Token
The provider's response can return the token in the response body or in a response header:
Under New Token Location, choose Response Body (JSON) or Response Header.
Enter the corresponding path:
For Response Body (JSON), enter the JSON path to the token (for example,
access_tokenordata.token).For Response Header, enter the exact header name (for example,
X-Auth-Token).
Optionally repeat the same choice under Token Expiry Location so wxrks knows exactly when the token expires (in seconds). Leave it blank if the provider doesn't return an expiry — wxrks then relies on a 401/403 response from the external service to trigger a refresh instead of proactive expiry tracking.
Set the Expiry Buffer (seconds) — how many seconds before actual expiration wxrks refreshes the token. Defaults to
60.
TIP: If the provider's token lifetime is short or unpredictable, raise the **Expiry Buffer** so pipelines never pick up a token that expires seconds after being fetched.
Step 5: Save and Verify the Status
Click Create Secret (or Update Secret). The button stays disabled until the Auth Endpoint URL, the New Token Location path, and a Client Secret are all present.
Reopen the secret to confirm the refresh configuration saved correctly. It shows an Active badge by default as soon as the configuration is saved — this is the starting state, not proof that a refresh has actually happened yet. Once a pipeline uses the secret for the first time and wxrks performs a real refresh, this section also shows a Last refreshed timestamp.
WARNING: If a refresh attempt fails, the status switches to **Failing** and account admins are notified by email the first time it happens. Repeated failures on an already-**Failing** secret do not send another email, so don't assume silence means it recovered — reopen the secret to check its current status and the recorded error message.
Use the secret in a pipeline exactly as before, with no changes needed to the pipeline definition itself:
${{ secrets.YOUR_SECRET_NAME }}
Every action type that reads secrets (HTTP calls, Slack messages, and others) resolves refreshable secrets automatically — there's nothing extra to configure on the pipeline side.
Troubleshooting & Common Errors
Issue / Error | Cause | Solution |
"Create Secret" / "Update Secret" button stays disabled | Auto-refresh is enabled but Auth Endpoint URL, the token path, or the Client Secret is missing. | Fill in all three fields. When editing, an existing Client Secret only needs to stay blank if one was already saved previously. |
Secret shows a "Failing" badge | The last refresh attempt errored — commonly an unreachable Auth Endpoint URL, an expired or incorrect Client Secret, or a New Token Location path that doesn't match the provider's actual response. | Open the secret to read the recorded error message and correct the relevant field. The fix takes effect the next time a pipeline uses that secret, when wxrks attempts the refresh again. |
Pipeline fails with "token refresh is already in progress on another node" | Multiple pipelines tried to refresh the same secret at once; one is refreshing while others waited past a short timeout. | This is expected under concurrent load and self-resolves. Re-run the pipeline; it picks up the freshly refreshed token. |
New secret works once, then pipelines start failing | The Token Expiry Location path or Expiry Buffer doesn't match how quickly the token actually expires. | Verify the expiry path against a real response from the provider, or increase the Expiry Buffer to refresh earlier. |
Quick Reference
Parameter | Specification |
Supported HTTP Methods for refresh |
|
New Token Location options | Response Body (JSON path) or Response Header (header name) |
Token Expiry Location options | Response Body (JSON path), Response Header (header name), or left blank |
Default Expiry Buffer | 60 seconds |
Secret name format | Uppercase letters, numbers, and underscores only |
Client Secret visibility | Write-only — never returned or displayed after saving |