Relay

Relay calls third-party APIs on your users’ behalf without exposing their credentials to your application. Send the request to WorkOS, and relay attaches the user’s credential server-side and streams the provider’s response back.

Relay is a forward HTTP proxy built for AI agents and other untrusted runtimes. With access tokens, your infrastructure fetches a provider access token and calls the provider directly, so the token exists inside the calling environment, where it can be copied, logged, or leaked. With relay, the token never leaves WorkOS: the agent authenticates with your WorkOS API key and names the user it acts for.

Every proxied request follows the same lifecycle:

1. Authenticate. Your WorkOS API key is verified and determines the environment. The key is stripped from the request and is never sent upstream.
2. Resolve the user. The X-Relay-User header identifies the user the request acts on behalf of, scoped by X-Relay-Organization when the connection belongs to an organization.
3. Look up the connected account. WorkOS finds the user’s Pipes connection for the provider you named. If the user hasn’t connected, or needs to re-authorize, the response is a 402 with an authorization_url to send them to.
4. Fetch the credential. The user’s access token is retrieved from the Pipes credential store, and refreshed automatically if it has expired.
5. Inject and forward. Relay control headers, cookies, and forwarding metadata are stripped, the provider credential is injected into the Authorization header, and the request is forwarded to the provider over HTTPS.
6. Stream the response. The provider’s status, headers, and body are streamed back verbatim, with an added X-Relay-Upstream-Status header.

Relay builds on your existing Pipes setup. You need:

• A WorkOS API key for the environment, from the API Keys section of the WorkOS Dashboard.
• The target provider enabled for your environment, configured in the Pipes section of the dashboard or through the data integration API.
• A connected account for the user, created when the user authorizes the provider through the Pipes widget or an authorization URL from the get authorization URL endpoint.

The base URL is https://api.workos.com/relay, and any HTTP method is accepted. To convert a direct provider call into a proxied one:

1. Keep the method, body, and content headers as they are.
2. Send the request to the relay base URL, and move the original URL into the X-Relay-URL header.
3. Replace the provider token with your WorkOS API key in Authorization.
4. Name the user in X-Relay-User, adding X-Relay-Organization for organization-scoped connections.

All other request headers, including Content-Type, Accept, and provider-specific headers, are forwarded unchanged. See limits and behavior for the headers that are stripped.

Put the complete upstream URL in X-Relay-URL. The provider is resolved from the URL’s host, so your code keeps working with the provider’s real URLs.

curl --request GET https://api.workos.com/relay \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "X-Relay-URL: https://api.github.com/user/repos?per_page=5" \
  --header "X-Relay-User: user_01EHZNVPK3SFK441A1RGBFSHRT" \
  --header "X-Relay-Organization: org_01EHZNVPK3SFK441A1RGBFSHRT"

Alternatively, prefix the provider’s API path with the relay base URL and the provider’s slug. The slug in the path selects the provider, and the path and query string are appended to the provider’s default API host, so /relay/github/user proxies to https://api.github.com/user.

curl --request GET "https://api.workos.com/relay/github/user/repos?per_page=5" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "X-Relay-User: user_01EHZNVPK3SFK441A1RGBFSHRT" \
  --header "X-Relay-Organization: org_01EHZNVPK3SFK441A1RGBFSHRT"

URL routing is the better default: it can reach any of a provider’s allowed hosts rather than only the default one, and it keeps the provider’s own URLs intact in your code and logs.

Pipes connections are either scoped to an organization or user-only, and the connection lookup requires an exact match on that scope:

• If the user authorized the provider under an organization, requests must include X-Relay-Organization with that organization’s ID.
• If the user authorized the provider without an organization, the header must be omitted.

When the user has no usable connection for the provider – they never connected, their grant was revoked, or the token can no longer be refreshed – the response is 402 Payment Required:

{
  "code": "relay_authorization_required",
  "connection": "github",
  "message": "User has not authorized provider \"github\"",
  "authorization_url": "https://github.com/login/oauth/authorize?client_id=..."
}

Surface the authorization_url to the user, let them complete the provider’s OAuth flow, then retry the original request.

authorization_url is null when WorkOS can’t build an authorization URL for the provider, which usually means the provider’s Pipes configuration is incomplete. Fall back to your own connection flow, such as the Pipes widget, instead of assuming the field is present.

On success you receive the provider’s status code, headers, and body exactly as the provider sent them, streamed as they arrive. Provider errors are passed through untouched, so a GitHub 404 comes back as a 404 with GitHub’s own error body.

Every proxied response carries an X-Relay-Upstream-Status header with the provider’s status code. Its presence means the request reached the provider, so you can distinguish an upstream 404 from a relay 404 such as an unknown provider.

Relay supports the following providers. With path routing, the request goes to the provider’s base API host. With URL routing, any listed host is allowed. The provider must also be enabled for your environment.

Each provider’s API domains are part of its WorkOS configuration, so this list grows as providers are added without any change on your side.

Errors generated by relay are JSON objects with code and message fields. Provider errors are passed through unchanged, so check for X-Relay-Upstream-Status to tell the two apart.