Content

How to Expose Internal APIs to AI Agents Safely

Handing an agent your internal OpenAPI spec and a service token exposes every endpoint by default. A curated, method-by-method allowlist plus policy guardrails is the safer default for APIs that were never built expecting an AI caller.

EngineeringNov 18, 2026

Key takeaways

  • -The naive approach, an OpenAPI spec plus one service token, exposes every endpoint the spec describes, whether or not the agent's task needs it
  • -A curated approach adds methods one at a time with swy add method, so only the specific calls a task actually needs are ever reachable
  • -Internal APIs often lack their own rate limits or abuse protection because they were built assuming only trusted internal callers, which makes policy guardrails matter more, not less, than for public APIs
  • -Credentials and traffic for an internal API never need to leave the network that already hosts it; there's no proxy hop, and Enterprise deployments run in the customer's own cloud and region
  • -A policy rule that holds high-value or irreversible internal calls for human approval is the same mechanism used for public APIs, just pointed at internal risk instead

Connecting an agent to a public SaaS API and connecting it to your own company's internal API are different problems wearing the same clothes. A public API is a fixed, documented surface someone else maintains; your internal API is whatever your own services expose, often with no clean separation between the three endpoints an agent should ever touch and the two hundred it technically could reach. The naive approach, handing the agent your internal OpenAPI spec and a service credential, exposes all two hundred by default and asks the model's judgment to narrow it down. That's backwards.

The naive way: hand over the spec and the credential

If an agent framework is given your internal API's OpenAPI spec directly and a service token that's valid for every endpoint in it, every endpoint in that spec becomes something the agent could call, whether or not it was ever meant to be agent-reachable. Endpoints meant for an internal admin tool, a batch job, or a service-to-service handshake get the same exposure as the one or two endpoints you actually wanted an agent to use. The model's own judgment about which calls are appropriate is the only thing standing between "intended" and "everything," and that judgment is not a security boundary.

The curated way: opt in method by method

Swytchcode treats any REST API with an OpenAPI spec or Postman collection the same way it treats a public SaaS integration: importing the spec makes the API's methods available to discover, but none of them are callable until you explicitly allow them with `swy add method`. That inverts the default from "everything is reachable unless removed" to "nothing is reachable until added," which is the direction that actually matches how a curated internal surface should work.

internal-api-setup.sh
# Import your internal API's spec. Nothing is callable yet.
swy get --openapi ./internal-api-spec.json --name internal-orders

# Discover what's in it
swy discover "cancel an order" --project internal-orders
swy info internal-orders.orders.cancel

# Only this one method becomes callable. Everything else in the
# 200-endpoint spec stays unreachable to the agent.
swy add method internal-orders.orders.cancel

The credential for your internal API is stored the same way as any other provider's: via `swy auth connect internal-orders`, in the local credential store, injected at execution time, never placed in the agent's own context or code. An agent that successfully calls `internal-orders.orders.cancel` still has no way to discover the service token itself, let alone use it to call an endpoint nobody added.

Policy on an internal API is often more important than on a public one

A public SaaS API usually already enforces its own limits on what a given API key can do; your internal API often doesn't, because it was built assuming only your own trusted backend services would call it. That makes the policy layer, not just the allowlist, worth setting up deliberately for internal APIs: a rule that holds a cancellation above a certain order value for approval, or blocks a call that targets a production-tier customer account from a method only meant for sandboxed test accounts, is control your internal API was never built to provide on its own.

policies.json
{
  "id": "hold-high-value-cancellations",
  "target": ["internal-orders.orders.cancel"],
  "when": { "field": "order_value_cents", "operator": ">", "value": 100000 },
  "action": { "type": "REQUIRES_APPROVAL", "message": "Order cancellations over $1,000 need a human to confirm" },
  "approval_timeout": "2h"
}

Where the credential and traffic actually live

For an internal API, where the call physically happens matters more than it does for a public SaaS integration, since an internal API is often only reachable from inside your own network in the first place. Swytchcode's architecture keeps that intact: there's no proxy hop, requests go straight from your own infrastructure to the provider, and on Enterprise, the whole deployment runs inside your own AWS, Azure, or GCP account, in a region you choose. An internal API that's only reachable from inside your VPC stays only reachable from inside your VPC; nothing about adding agent access to it routes traffic through a third party.

FAQ

Does importing an OpenAPI spec make every endpoint in it callable?

No. Importing a spec makes its methods available to discover and inspect with `swy discover` and `swy info`. None of them are callable by an agent until you explicitly add them one at a time with `swy add method`. A 200-endpoint internal API can be reduced to the 2 or 3 methods you actually intend to expose.

Where does the credential for an internal API get stored?

The same place as any other provider's: locally, via `swy auth connect`, injected into the request at execution time. The agent's own context or code never holds it, so a successful call doesn't give the agent, or anything that compromised the agent's reasoning, a reusable credential.

Can an internal API's own rate limits or auth replace a policy layer?

Usually not fully. Internal APIs are often built assuming only trusted internal services call them, so they frequently lack the kind of request-level limits a public API enforces by default. A policy file that reads the call's own arguments fills that gap specifically for the agent-facing surface, without requiring changes to the internal API itself.

Does this work the same way for an internal API with no OpenAPI spec at all?

A Postman collection works the same way as an OpenAPI spec for this purpose. If neither exists, writing a minimal OpenAPI description of just the handful of endpoints you intend to expose is usually less work than it sounds, and it has the side benefit of documenting exactly what an agent can reach.

Swytchcode resources

More content