Connect an authenticated API securely

Turn an API into a tool covers building a connector. This guide is about doing it for an API that needs authentication — an API key, bearer token, or password — without ever putting that secret in front of the AI.

Your secret never reaches the model

You define the connector and its authentication type; the secret value is a separate thing a person adds in the dashboard. From then on:

• The secret is encrypted at rest and injected by apistash only at the moment the request is made.
• It is never returned by the API and never shown to the agent — the model sees only the structured result of the call, not the credential that authorized it.

So an agent can use a tool that calls an authenticated API without ever being able to read, leak, or exfiltrate the underlying key.

Define the auth type, add the secret separately

A custom tool declares one of these authentication schemes — the type only, no secret:

auth type	Sends
{ "type": "none" }	Nothing — an unauthenticated API.
{ "type": "bearer" }	Authorization: Bearer <secret>
{ "type": "basic" }	HTTP Basic auth with a stored password.
{ "type": "header", "header_name": … }	The secret in a header you name.

Because secrets never travel over MCP, a tool created for an authenticated API is created disabled. A person adds its secret and then enables it in the dashboard. A none-auth tool skips the secret step; its initial enabled state follows the owner's default setting. In either case, a credential can call the tool only when the access model makes it reachable. (See create_custom_tool.)

{
	"name": "issue-tracker",
	"description": "Look up an issue by key",
	"connector": {
		"http_method": "GET",
		"url_template": "https://api.example.com/issues/{key}",
		"input_schema": {
			"type": "object",
			"properties": { "key": { "type": "string" } },
			"required": ["key"]
		},
		"auth": { "type": "bearer" }
	}
}

This comes back enabled: false. Add the bearer token and enable the tool in the dashboard. An agent whose credential can reach it can then call it — still without ever seeing the token.

Safe by construction

A connector can only reach public HTTP/HTTPS endpoints. Requests to private, loopback, link-local, and cloud-metadata addresses are rejected, redirects are not followed, and response size and duration are capped. So a custom tool can't be steered into probing your internal network — it's a deliberate boundary, not a limitation to work around. (See Custom Tools → Safe by construction.)

tip

Combine this with a least-privilege key so only the agents that should call the authenticated tool can even see it.

Good to know

• An agent can define the tool; a person adds the secret. A standalone personal credential uses a bare name; in organization scope, me/name selects the represented member's private space and <team>/name a bound team. The secret and any org-catalogue publishing stay dashboard actions.
• Update the connector in place with update_custom_tool if the API changes; the stored secret carries over.
• Each plan caps how many custom tools you can create — see Plans & Limits.