Skip to content

Per-user credentials with an OAuth gateway

Updated October 29, 2026

This page explains how to let each person use your server with their own rights on your API, through an OAuth gateway placed in front of Voozeo. Voozeo stores no credential.

Principle

By default, a server calls your API with one secret shared by everyone. With the "Forwarded by caller" authentication type, Voozeo instead forwards to your API, for each tool call, a header it received on the MCP call: same name, same value.

  1. The AI connects to an OAuth gateway, not to Voozeo.
  2. On the gateway's consent page, the person types their own credential for your API (a token, a key).
  3. For each call, the gateway relays it to your server's URL that contains the key (https://mcp.example.com/k/<key>/mcp), adding the header, for example Authorization: Bearer <token>.
  4. Voozeo forwards this header as is to your API: every user acts with their own rights. Nothing is stored, neither the credential nor a copy of it.

Setup

  1. In the "Target API" tab, choose "Forwarded by caller". The "Header name" field is prefilled with authorization; enter another name if your API expects a different header (for example X-User-Token). Some names, managed by Voozeo or the network, are refused (host, cookie, content-type, user-agent, names starting with x-forwarded-, x-amz-, x-amzn- or mcp-…). Click "Save".
  2. If the server used OAuth 2.0 before, it has no active MCP key after the change and the "Connection" tab says so: regenerate the key. The key stays required: the gateway sends it in the URL.
  3. In the "Connection" tab, the "OAuth gateway" block shows the URL https://mcp.example.com/k/<key>/mcp to declare in the gateway (the real one is in the tab, with <YOUR_KEY> until you regenerate the key).

This URL contains the server key: do not give it to users, only to the gateway. If the header is Authorization, only this URL can forward the credential: on the URL where the key travels in the Authorization header, that header is the MCP key and is never forwarded. The "Connection" tab then hides the blocks that use that URL. With another header, both URLs work.

Example with CKOAuth

In CKOAuth, create a connector in bearer mode (or header mode if your API expects another header) whose target is the URL https://mcp.example.com/k/<key>/mcp. In header mode, enter the header name set in Voozeo; add the optional prefix your API expects, for example Bearer . The AI connects to CKOAuth with OAuth, the person enters their credential on the consent page, and CKOAuth injects it on each call.

In the sandbox

For a forwarded server, the "Test" tab shows a masked "Forwarded credential" field for the API tools: enter the exact value your API expects, for example Bearer abc123. It is sent for this run only and kept in the memory of the tab: it is not stored, and it disappears when you leave the page. Without a value, the API tool is refused (CREDENTIAL_REQUIRED) without counting toward your quota. Document tools do not need it.

Limits

  • A server has a single key: the gateway uses it for all users. Quotas are shared by all the users of the server.
  • A changed or revoked credential shows up as an appel_http tool error with status 401 or 403 in the Call log.
  • When the header is missing from the call, the AI receives a tool error Missing credential: the "<name>" header is required by this server.; the call is not counted.
  • The diagnostic mode of the log never captures the credential: it is masked.
Get started