Use this recipe when an external API expects an Authorization: Bearer ... header and the access token can expire.

Payloads handles this through a Bearer Token Credential and a generated Credential Payload. The Credential stores the token state. The Credential Payload describes how Payloads should call the token endpoint and update the Credential when a new access token is returned.

For the detailed Credential article, see Configure Bearer Token Credentials.

The finished setup has three parts.

Users should not usually create Credential Payloads manually. Payloads creates them automatically when you create a Bearer Token Credential.

Create a Credential with type Bearer Token.

Enter the values required by the external API, such as client id, client secret, access token, refresh token, and access token duration. The exact values depend on the API you are connecting to.

The Bearer Token Credential is the record your outbound Payloads reference.

Use sandbox-safe credentials while testing. Do not paste production secrets into screenshots, tickets, or documentation.

After the Credential is created, Payloads creates a related Credential Payload.

Open that Payload to configure the token refresh request. This is a normal Payload configuration experience: Endpoint, Method, body, headers, parameters, response body, and Data Targets.

The generated Credential Payload controls how Payloads asks the external API for a fresh token.

The Credential Payload should call the external token endpoint and parse the response values Payloads needs to store back on the Credential.

Model the response body returned by the token endpoint.

At minimum, map the returned access token. If the API returns expiry or refresh token values, map those too when they should update the Credential.

The response body tells Payloads where the refreshed token values appear in the token endpoint response.

Use Data Targets to update the Credential fields from the token response. This keeps the token state on the Credential record rather than duplicating token logic in every outbound Payload.

Open each outbound Payload that needs this authentication and select the Bearer Token Credential.

At runtime, Payloads uses the Credential to add the generated bearer Authorization header. The outbound Payload should focus on the business API request, not on rebuilding token authentication each time.

For outbound setup, see Configure an Outbound Payload.

Run the Credential Payload manually first.

Check the Job:

Then run an outbound Payload that uses the Credential and confirm the external API accepts the bearer header.

If the refresh succeeds but the outbound API call fails, troubleshoot the outbound Payload separately. If the refresh fails, focus on the Credential Payload's endpoint, body, headers, response mapping, and Data Target output.

Do not manually add a second bearer Authorization header to each outbound Payload.

Do not create separate Credential Payloads for the same Credential unless you are intentionally replacing the generated refresh configuration.

Do not share exported Credential configuration casually. Export previews redact secrets, but copied or downloaded migration files can include the original values.