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.
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.
# 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.cancelThe 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.
{
"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
- Your API, your OAuth app, your rules: https://www.swytchcode.com/blogs/your-api-your-oauth-app-your-rules
- How to set up policy guardrails for AI agents: https://www.swytchcode.com/blogs/how-to-set-up-policy-guardrails-for-ai-agents-with-swytchcode
- tooling.json, manifest.json, and policies.json explained: https://www.swytchcode.com/blogs/tooling-json-manifest-json-and-policies-json-explained-swytchcode-s-config-files
- A prompt is not a policy: guardrails and human approval: https://www.swytchcode.com/blogs/a-prompt-is-not-a-policy-guardrails-and-human-approval-for-ai-agents
- Designing a CLI for AI agents, not humans: https://www.swytchcode.com/blogs/designing-a-cli-for-ai-agents-not-humans
- Swytchcode pricing: https://www.swytchcode.com/pricing
More content
API Governance Tools That Block a Pull Request When a Policy Check Fails
Spectral, Redocly CLI, and vacuum all fail a PR's CI check when an OpenAPI spec breaks a governance rule. How the gate is actually wired up, and why it's a different layer from Swytchcode's own runtime policy checks.
API Governance Tools With a Free Tier: What Small Teams Can Actually Use
Most API governance comparisons assume an enterprise budget. Here's what's genuinely free with no catch, what's gated behind a paid plan, and the realistic free stack a small team can actually run.
API Spend Caps for AI Agents: Capping Cost Before the Invoice Does
Most teams find out an agent overspent on a metered API when the invoice arrives. An argument-level policy that caps the metric a provider actually bills on, checked before the call goes out, catches it in the moment instead.
