Pass-through headers authentication

Pass-through headers is an authentication option for API tools and MCP servers that forward HTTP headers from your request directly to the external API your tool calls. This is useful when the external API accepts the same credentials you already use to access Devs.ai. For example, an SSO token or an internal API key.

Instead of storing separate credentials for each tool, your existing authentication context flows through automatically.

When to use pass-through headers

• Enterprise SSO: Your internal APIs accept the same SSO token you use to log in to Devs.ai.
• API gateways: You need to forward Authorization headers to services behind a gateway.
• Distributed tracing: You want to pass correlation or request IDs through to backend services.
• Custom authentication: Your internal APIs require proprietary headers that you already send to Devs.ai.
• MCP servers: Your MCP server endpoint requires authentication using the same headers you provide to Devs.ai.

Setting up pass-through headers

1. Navigate to your agent's Tools configuration.
2. Create or edit an API tool (REST or GraphQL).
3. Under Authentication, select Pass-Through Headers.
4. Choose your forwarding mode:

• Forward all eligible headers (default) — Within the rules below, all non-restricted headers from your request are forwarded to the external API.
• Custom header mappings — Check Customize pass-through headers to specify exactly which headers to forward, and optionally rename them.

5. Save the tool.

Connector URL scoping (default)

For API tools, forwarded headers are tied to the configured API URL of the connector. By default, that prevents sensitive headers (including authentication tokens) from being sent to other hosts if the tool follows a redirect or issues a secondary request outside that URL. This behavior is part of the platform’s connector security model—use the in-product labels and any advanced options as the source of truth for your tenant.

MCP servers that use pass-through headers follow the same general idea: your sign-in context is forwarded only where the integration expects it, not broadly across unrelated endpoints.

Custom header mappings

With custom mappings, you control precisely which headers are forwarded and what they're called on the other side:

Source header (from your request)	Target header (sent to external API)
Authorization	Authorization
X-Internal-Token	X-API-Key

• Source header name: The header captured from your incoming request (matching is case-insensitive).
• Target header name: The header name used when calling the external API. If left empty, it defaults to the source name.

You can add as many mapping rows as needed.

Calling the API with headers

When you send a chat request to Devs.ai, include the headers you want forwarded:

curl -X POST https://devs.ai/api/v1/chats/{chatId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-sso-token>" \
  -H "X-Internal-Token: <your-api-key>" \
  -H "X-Correlation-Id: abc-123" \
  -d '{"prompt": "Look up order #12345", "date": "2026-02-11T00:00:00Z"}'

If the agent has a tool configured with pass-through headers, the Authorization, X-Internal-Token, and X-Correlation-Id headers will be forwarded when the tool calls the configured API URL (subject to URL scoping and the exclusions below). No changes to the request body are needed — headers are extracted transparently from the HTTP request.

Comparing authentication types

Auth type	Best for	How credentials are managed
None	Public APIs with no authentication	N/A
API Key	APIs with static keys	Admin configures the key in tool setup
OAuth	APIs requiring OAuth 2.0	System manages tokens after user authorization
Pass-through headers	Internal APIs and MCP servers sharing your auth context	You provide headers in your request to Devs.ai

Security and restrictions

URL scoping and redirects

Even when you forward all eligible headers, the platform applies URL scoping so forwarded credentials are not blindly attached to follow-up requests that leave the connector’s configured API URL. That reduces the risk of leaking tokens when a remote server redirects or chains calls.

Blocked header names

Some headers are never forwarded, regardless of your configuration:

• Cookie headers (cookie, set-cookie) — Excluded to prevent session data from leaking to external endpoints.
• Connection headers (host, connection, content-length, transfer-encoding, etc.) — These are connection-specific and should not be forwarded.

Even if you configure a custom mapping that includes cookie as a source, it will not be forwarded. This is a deliberate security measure.

Best practices

• Use custom header mappings when possible to forward only the headers your external API needs.
• Only use pass-through headers with trusted endpoints. Since your authentication context is forwarded, make sure the external API is one you trust.
• Remember URL scoping — behavior on redirects and secondary requests is constrained for security; if an integration breaks after a provider change, confirm the tool’s base URL and redirect chain.
• Prefer API Key or OAuth for public third-party APIs that have their own credential management.
• Regularly audit which tools use pass-through headers authentication.

Good to know

• Headers are not stored — they exist only for the duration of the request.
• Header name matching is case-insensitive, but the forwarded name preserves the original case (or uses the target name if you specified a mapping).
• No environment variables or feature flags are required. The feature is available to anyone who can create or edit API tools.
• Pass-through headers work with both API tools and MCP servers.