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 provider credential 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 reconnect, relay returns a 402 response.
4. Resolve the credential. WorkOS retrieves and refreshes OAuth access tokens, retrieves stored API keys, or mints access tokens from stored client credentials, depending on how the account is connected.
5. Inject and forward. Relay control headers, cookies, and forwarding metadata are stripped, the provider credential is injected into the provider’s configured request header, and the request is forwarded 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 through the provider’s OAuth flow, by entering an API key, or with the client credentials endpoint.

Relay uses the connected account’s authentication method – OAuth, API key, or client credentials – without changing the relay request format. The provider’s Relay configuration determines which methods it accepts and how the credential is presented upstream.

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. Authenticate 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. Name the provider explicitly with X-Relay-Provider when the host is ambiguous, or when you would rather not depend on host inference.

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 OAuth grant was revoked, or their 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=..."
}

For OAuth connections, surface the authorization_url, let the user complete the provider’s authorization flow, then retry the original request.

authorization_url is null for API key and client credentials connections. Collect or rotate those credentials through the Pipes widget, the upsert API key endpoint, or the client credentials endpoint, then retry. It can also be null when a provider’s OAuth configuration is incomplete.

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 active providers below. 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.

The Authentication column shows the methods explicitly configured for each provider. Relay can also mint tokens for eligible client credentials connections; contact support to confirm provider eligibility during early access.

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.