Skip to content

Target API and authentication

Updated October 29, 2026

The target API is the real API that Voozeo calls each time an AI uses a tool. This page explains how to set it up.

Base URL

In the "Target API" tab, the "Base URL" field is the public HTTPS address of your API, with no query parameters or fragment (https://api.example.com/v1, not https://api.example.com/v1?x=1). If your spec contains one, it is suggested with the "From the spec" label; you can also enter your own. A value you entered yourself is never overwritten by a new import, and "Use the spec URL" brings the spec value back. Without a base URL, the tab asks you to import a spec or enter it.

Authentication

Choose the authentication type your API expects.

None

Calls go out without credentials. Suitable for public APIs.

API key

Fill in the "Name" of the header or parameter (HTTP token characters: letters, digits and the characters !#$%&'*+-.^_|~ or the backtick, 128 characters at most), its "Location" ("Header" or "Query parameter") and the "Secret". For example, the name X-Api-Key in a header. Some headers, managed by Voozeo, cannot be used.

Bearer token

Enter the token: it is sent in the Authorization: Bearer <token> header.

Basic

Enter the "Username" (without the : character) and the "Password". They are sent as HTTP Basic authentication.

OAuth 2.0

With OAuth 2.0, each person who uses your server through an AI signs in with their own account at your API provider. Voozeo then calls your API with that person's token, never with a shared secret. The AI does not use an MCP key: see Servers using OAuth.

  1. At your API provider, create an OAuth app (for example "OAuth apps" in the developer settings). Copy into it the "Callback URL to declare with your provider" shown in the tab, exactly as it is.
  2. Back in the "Target API" tab, choose "OAuth 2.0" and fill in the "Client ID" and the "Client secret" given by the provider.
  3. Fill in the "Authorization URL" and the "Token URL" of the provider, in https://. The authorization URL must not already contain the parameters Voozeo adds (state, redirect_uri, client_id, response_type, code_challenge, code_challenge_method).
  4. Choose the "Scopes" to request (50 at most), the "Client authentication method" (client_secret_basic, the default, or client_secret_post when the provider expects the secret in the request body, as GitHub does) and, if the provider asks for it, the "Audience".
  5. Click "Save".

If your OpenAPI declares an OAuth 2.0 scheme with the authorization code flow, the URLs are prefilled and marked "Detected in your OpenAPI", and its scopes are listed as checkboxes, unchecked. Check the values with your provider: they are only a suggestion.

Switching a server to OAuth 2.0 asks for the client secret, and the MCP key stops working at once. Voozeo always uses PKCE with the provider.

Forwarded by caller

Voozeo stores no secret: for each tool call, it forwards to your API the header it received on the MCP call, with the same name and the same value. Enter the "Header name" (authorization by default). The value typically comes from an OAuth gateway placed in front of Voozeo, so that each user acts with their own rights: see Per-user credentials with an OAuth gateway. If the header is Authorization, only the URL that contains the key can forward it. Switching to this type deletes a stored secret; coming from OAuth 2.0, the MCP key must be regenerated.

Write-only secret

The secret is at most 4,096 characters long. It is stored encrypted and is never displayed again after saving: the tab only says "Configured". To change it, click "Replace" and enter the new value. If you switch back to "None", the stored secret is deleted. The AI never sees this secret.

With OAuth 2.0, the secret is the client secret of your OAuth app. It is only sent to the token URL. You must enter it again when you switch to OAuth 2.0, or when you change the client ID or the token URL.

Active authorizations

On an OAuth 2.0 server, the "Target API" tab shows "Active authorizations: n", the number of AI connections currently signed in ("1,000+" beyond that).

  • "Revoke all authorizations" disconnects every AI after a confirmation: each one will have to sign in again on its next call.
  • Changing the authentication type, the client ID, the authorization URL or the token URL revokes every authorization as well; the tab warns you before you save. Changing the scopes, the audience, the method, the secret or the base URL revokes nothing.
  • A person can also withdraw access from their account at the API provider (the list of authorized OAuth apps).

What the AI receives

With OAuth 2.0, each call goes out with the token of the person connected through the AI; the AI never receives this token. Your API's response is passed to the AI as HTTP <status>, followed by the body. A JSON body is reformatted to be readable.

  • Beyond 100 KB, the text is truncated and the note "[Truncated: the response exceeded 100 KB]" is added. Voozeo only reads 1 MiB of a response anyway.
  • Binary content is summarized as [binary content: N bytes, type].
  • A status of 400 or more is flagged as a tool error (isError), and the body stays visible so the AI can understand.
  • If the spec declares an output format that the response does not follow, the error is flagged as well.

Call errors

  • The API does not answer within 10 seconds: the AI receives a "did not respond within 10 seconds" message.
  • The API is unreachable: "could not be reached" message.
  • The address is forbidden (a private network, for example): the call is refused.
  • Redirects are followed up to 3 times.

Every call, successful or not, is visible in the Call log.

Example

Your API expects a key in the X-Api-Key header. You enter the base URL https://api.example.com, choose "API key", name X-Api-Key, location "Header", paste the secret and click "Save". The secret then shows as "Configured". A call to get_order returns, for example:

HTTP 200

{
  "id": "A-1042",
  "status": "shipped"
}
Get started