Pass-Through Headers Authentication

Pass-through headers is an authentication option for API tools and MCP servers that forwards 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) — 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.

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 is called. 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

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.
• 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.