Skip to main content

Double-Hop Authentication

Double-hop authentication lets your website or app pass the current visitor's auth context to the widget so API calls can run as that visitor.

When You Need It​

Use double-hop authentication when the AI agent needs to answer questions that depend on the logged-in visitor.

Examples:

  • "Where is my order?"
  • "Cancel my appointment."
  • "Show my invoices."
  • "Update my shipping address."

If the API can be called with the same server key for every visitor, you may not need double-hop auth.

How It Works​

What Your App Provides​

Your app provides a short-lived token or auth value that your API already understands.

Examples:

  • Visitor access token.
  • Session-bound API token.
  • Temporary delegated token.

Use short-lived tokens whenever possible.

For Bearer-token bridges, pass the raw token value. InstaMCP adds the Bearer prefix when the bridge auth type is configured as Bearer.

What InstaMCP Provides​

InstaMCP uses that visitor auth value only for the current widget request or session. The integration key still controls which integration and tools are allowed.

Common Setup Shape​

  1. Your visitor signs in to your app.
  2. Your app obtains a visitor-specific token.
  3. Your app sends that token to the widget for the correct bridge or deployment.
  4. The visitor asks a question.
  5. If the AI agent calls an API tool, the visitor token is included for that call.

Widget Chat and Voice Setup​

For the embedded widget, send an MCP_AUTH_UPDATE message to the widget.

The important part is the tokens map:

  • Key: bridge/project ID or deployment ID.
  • Value: the visitor token for that bridge.

Example:

const visitorToken = await getVisitorApiToken();

widgetFrame.contentWindow.postMessage(
  {
    type: "MCP_AUTH_UPDATE",
    data: {
      tokens: {
        "BRIDGE_OR_DEPLOYMENT_ID": visitorToken
      }
    }
  },
  "*"
);

Use the bridge/deployment IDs shown in the integration setup. If the integration has multiple bridges enabled, include one token entry for each bridge that needs visitor-scoped auth.

The widget includes this map in chat and voice requests as mcp_auth_overrides. During tool execution, InstaMCP matches the current tool's deployment ID or bridge/project ID and injects the matching token into that tool call.

Direct MCP Gateway Setup​

For direct public MCP gateway usage, select the deployment and optionally pass the visitor token as a header:

X-MCP-Deployment-Id: YOUR_DEPLOYMENT_ID
X-MCP-Auth-Token: YOUR_VISITOR_TOKEN

Also pass the integration key:

X-Product-Key: YOUR_INTEGRATION_KEY

If an integration has more than one MCP deployment enabled, X-MCP-Deployment-Id or the deployment_id query parameter is required so InstaMCP knows which bridge to call.

For direct gateway calls, X-MCP-Auth-Token is injected into tools/call arguments as mcp_auth_token.

Security Checklist​

  • Use short-lived visitor tokens.
  • Do not hardcode visitor tokens in the page source.
  • Do not use one visitor's token for another visitor.
  • Keep integration keys limited to allowed domains.
  • Disable tools that should not be callable by end users.

Troubleshooting​

If visitor-specific API calls fail:

  • Confirm the visitor is signed in.
  • Confirm the token is fresh.
  • Confirm the token map key matches the bridge/project ID or deployment ID.
  • Confirm the bridge auth setting is compatible with runtime token overrides.
  • Confirm the correct bridge or deployment is attached to the integration.
  • Confirm your API accepts the token format being passed.