API version upgrade security for AI agents

An API version upgrade can expand an agent's authority without changing a single line of the agent's instructions. The dangerous changes usually look harmless in a release note: a default shifts, an endpoint appears, a legacy token gains a compatibility path, or a response includes records that the old version omitted.

Human-operated integrations sometimes survive that ambiguity because a person notices an unfamiliar screen or pauses before an odd request. An autonomous coding agent does not supply that pause. If it can form requests from documentation, inspect errors, and retry alternatives, any newly reachable operation becomes part of its practical authority.

Version labels do not measure authority

A version number describes an API provider's compatibility promise, not the permission change an agent experiences. Treat every API upgrade as an authority review until you compare what the credential could do before and after.

The Semantic Versioning specification says that a MAJOR version changes when an incompatible public API change occurs. That statement helps library maintainers decide whether callers may break. It does not say that a MINOR release cannot add a new administrative endpoint, broaden a default filter, or accept an access token in another audience. All three can preserve compatibility while increasing what an agent can accomplish.

This distinction matters because teams often ask the wrong question: "Will our code still run?" The question that protects the account is: "What operations can this existing agent process now make successfully, against which resources, with which credential?"

An API upgrade has four separate surfaces:

• Request compatibility: methods, paths, parameters, and payload formats.
• Resource reach: the accounts, projects, repositories, files, or records that a request can address.
• Action reach: the read, write, delete, deploy, billing, and identity operations that can complete.
• Credential acceptance: which tokens, keys, signatures, audiences, and scopes the provider accepts.

A green test for request compatibility says almost nothing about the other three. That is why a change can pass a conventional regression suite and still give an agent a new route to production data.

Do not assume that a dated API version solves this problem. A provider can keep a dated surface stable while changing a shared authentication service, adding opt-in fields that an agent discovers, or altering defaults outside the endpoint path. Pinning a version is useful. Calling a pin a permission boundary is careless.

Build the before-and-after authority map

You cannot review an upgrade from a changelog alone. Build a compact map of the requests the agent may issue, then compare observed behavior in the old and new versions.

Start with actual traffic, not the intended design. Agents frequently use more endpoints than the original task implies: discovery calls, retries after validation errors, pagination, lookup endpoints that translate names into IDs, and convenience APIs suggested by error messages. Include those calls because they can reveal resource identifiers or grant a wider route than the planned action.

For every request family, record these facts:

The map should name the resource boundary in plain language. "Can call deployments API" is too vague. "Can create deployments only in the sandbox project" can be tested. If the provider does not expose enough detail to state that boundary, use a separate test identity for the agent until you can establish it.

Then make a two-column comparison. Run the same request corpus against the old and new versions with an isolated account that contains deliberately separated resources: at least one allowed project, one forbidden project, one inactive record, and one account under a different tenant if the service supports tenancy. The test data needs recognizable names so you can spot accidental spillover in results.

Do not compare only status codes. A 200 response can hide the difference that matters: twice as many records, a new next_page link that crosses a boundary, an extra credential field, or an object identifier that lets the agent call a privileged endpoint later. Compare response shape and identifiers, then inspect any new fields for follow-on authority.

Changed defaults create access paths nobody requested

An omitted parameter is still an authorization decision when the server chooses its meaning. Changed defaults deserve the same review as a new write endpoint.

The familiar failure starts with a harmless-looking list request. Version one requires project_id and returns only active records. Version two permits the request without project_id, and the provider defines the omission as "all projects visible to this token." The agent's source code did not change if it had already omitted that optional field. Its reachable data did.

Other defaults produce the same result:

• A list endpoint begins including archived, deleted, or inherited objects.
• Pagination moves from a small fixed result set to cursor traversal with a next URL.
• A create endpoint chooses the caller's default workspace instead of rejecting a missing workspace ID.
• An update endpoint accepts omitted fields as "preserve current value" rather than requiring an explicit concurrency version.
• A search endpoint begins indexing content from connected services.

Providers call these improvements because they reduce client work. For an agent, reduced client work often means less friction before an action reaches a broader target.

Review defaults with deliberately incomplete requests. For each optional parameter, send a request with the parameter absent, present with an empty value if the API permits it, and present with an explicit safe value. Compare the target set and the server's error. An agent that generates requests will try omitted fields naturally, especially after it sees a documentation example that leaves them out.

Do not rely on prompt text such as "only use project A" to contain this. Prompt instructions influence the request choice, but the API decides whether a request can touch project B. Put the project boundary into the credential, the endpoint design, or a gateway that validates the request before it leaves the machine.

Added endpoints make broad credentials broader

A new endpoint changes an existing credential's authority if that credential can authenticate to it. The agent does not need to have called the endpoint before the upgrade for the risk to exist.

Teams often exclude added endpoints from review because they call them "new functionality." That logic works only when a human user gets a new UI control and an administrator separately grants access. It fails when a bearer token with a broad scope automatically works against the new route.

Suppose an agent has a token described as projects:write. In version one, that token can create and edit project metadata. Version two adds POST /projects/{id}/exports, which creates a downloadable export and uses the same scope. The token's scope string did not change, but the effect of possessing it did. The agent may discover that endpoint through an API schema, a generated client, an error hint, or plain documentation.

Classify new endpoints by effect rather than by HTTP verb. GET endpoints can expose source code, secret values, audit history, personal data, or signed download URLs. POST endpoints can create irreversible costs or trigger external workflows. A DELETE route may be less dangerous than a GET route that reveals a credential usable elsewhere.

Review each new route against four questions:

1. Does an existing agent credential authenticate successfully?
2. Which existing scopes, roles, or API-key classes permit it?
3. Can its output supply identifiers, URLs, or tokens for another operation?
4. Can the agent reach it through the client library, discovery document, or supplied documentation?

The last question catches a common bad recommendation: "We will not tell the agent about the new endpoint." That restriction feels practical because agents follow their working context most of the time. It is not a control. Agents can inspect schemas, infer conventional paths, or be instructed by a later task. A server must reject an unapproved operation even when the client knows its exact URL.

If the provider cannot separate the new route from an old broad scope, create a narrower integration identity before upgrading. A token intended for one narrow workflow should not inherit every future meaning that a provider assigns to a friendly scope name.

Authentication changes are permission changes

Authentication behavior belongs in the upgrade review because accepting a credential differently changes who can act. Teams frequently test successful login and skip the denial cases where an upgrade does its damage.

OAuth 2.0 defines access tokens as credentials that represent an authorization grant, while RFC 9700, OAuth 2.0 Security Best Current Practice, calls for exact redirect URI matching and describes protections around token replay and sender-constrained tokens. The practical lesson is broader than OAuth: a token's format alone does not establish its intended recipient, sender, or scope. The resource server must enforce those properties on every accepted request.

Version changes often touch that enforcement indirectly. A provider may introduce a new issuer, accept tokens intended for a sibling API, add a token exchange route, alter refresh-token rotation, or allow a legacy API key alongside a scoped token. Compatibility pressure makes these changes tempting. It also creates alternate paths that engineers forget to test.

Test both acceptance and rejection. For each credential class, try the allowed operation, the same operation against a forbidden resource, an expired credential, a token with an incorrect audience, a token with missing scope, and a revoked credential. If the provider supports refresh tokens, test whether a refresh preserves the old grant, changes its audience, or silently gains scopes granted during a later consent flow.

A useful record looks like this:

credential: build-agent-sandbox
request: POST /v3/projects/prod-42/deployments
expected: 403 forbidden
old version: 403 {"error":"insufficient_scope"}
new version: 201 {"id":"dep_...","environment":"production"}
review result: block upgrade and revoke credential

The response body matters. A 403 that becomes a 404 may be an intentional information-hiding change. A 403 that becomes 201 is an authority increase, even if the changelog calls it improved compatibility.

Also examine header behavior. Custom headers can select an API version, organization, or impersonated user. If the new API treats a missing header as a default organization, an agent's retry after a header formatting error can land in the wrong place. Record exact headers in tests, with secrets redacted, and test omission separately.

Agent behavior turns small deltas into full workflows

An agent can chain individually ordinary calls into a result that the API designer never reviewed as one permission. Version review must follow those chains.

A new list field may reveal a repository ID. That ID may feed a download endpoint. The download response may include a signed URL. The URL may expose an artifact whose configuration contains another service endpoint. Each call can appear allowed on its own. The combined sequence can exceed the task the agent received.

This is why endpoint-by-endpoint authorization review is necessary but incomplete. Add workflow tests for the actions you want the agent to perform and for nearby actions you want to exclude. Trace identifier flow between calls: IDs, pagination cursors, locations, presigned URLs, job IDs, and error messages that disclose valid resource names.

Keep the tests concrete. If the agent should update an issue in one repository, test that it can:

• Read the intended issue and update its permitted fields.
• Fail when it tries another repository's issue ID.
• Fail when it tries to alter repository settings or webhooks.
• Fail when it follows a link to an export, member list, or token management route.

The failure path matters as much as the success path. An agent handles errors as information. A detailed denial that names an alternate endpoint may make an unintended route easier to find. You may accept that tradeoff for human developers, but you should know it exists before exposing the integration to an autonomous process.

Limit retries during upgrade tests. A retry policy that was harmless when a request was idempotent can create duplicate actions if the new version changes idempotency handling or returns a timeout after completing work. Verify whether the API uses an idempotency key, how long it retains that key, and whether the version upgrade changes the header name or request hashing rules.

A capability diff catches changes ordinary tests miss

A capability diff is a repeatable test that asks which requests a credential can complete, not whether your application still receives expected data. Keep it small enough to run for every version candidate.

Create a request corpus in a repository that contains no production secrets. Use environment variables for test tokens and target only a disposable account. The following shell pattern records the parts that expose changed authority while avoiding credential output:

curl -sS -D headers.txt -o body.json \
  -H "Authorization: Bearer $TEST_TOKEN" \
  -H "X-API-Version: 2025-01-01" \
  "https://api.example.test/v1/projects?limit=2"

printf 'status: ' && head -n 1 headers.txt
printf 'headers:\n' && grep -Ei '^(link|location|x-request-id|www-authenticate):' headers.txt
printf 'identifiers:\n' && jq -r '.. | objects | (.id? // empty)' body.json | sort -u

Run the corpus once for each version, then compare status, selected headers, and normalized identifiers. Do not blindly diff full JSON. Timestamps, request IDs, and ordering create noise that trains reviewers to ignore diffs. Normalize those fields first, but preserve pagination links, resource IDs, role names, and any field that can direct a later request.

Your corpus should include successful requests, expected denials, omitted optional parameters, and the first page plus a pagination follow-up. Add one request per newly documented route that looks related to an existing agent scope. The point is not to enumerate the whole provider. The point is to cover every operation the agent can realistically discover or combine.

A simple result file makes decisions reviewable:

{
  "case": "forbidden-production-deploy",
  "credential": "build-agent-sandbox",
  "request": "POST /v3/projects/prod-42/deployments",
  "expected_status": 403,
  "observed_status": 403,
  "observed_resource_ids": [],
  "version": "2025-01-01"
}

Require an explicit reviewer decision for every difference. "Expected because the provider changed it" is not a decision. The reviewer must state whether the new behavior remains within the agent's approved authority, and if so, where that authority is enforced.

Logs prove what happened, not what should have happened

Request logs help investigate an upgrade, but they do not replace a pre-deployment authority review. They answer different questions.

Before the upgrade, the capability diff tells you whether the provider will accept an unwanted request. After the upgrade, logs tell you whether the agent actually attempted it, what process made the attempt, and whether you need to contain the account. You need both because a denied request today can become accepted after a provider-side behavior change tomorrow.

Log the version selector, normalized operation, target boundary, credential label, decision, status, and correlation ID. Do not log bearer tokens, raw authorization headers, full request bodies, or secret-bearing response fields. A security log that stores the credential it was meant to protect merely moves the breach.

Separate a session record from an action record. The session answers which agent process received permission to operate during a run. The action record answers which individual request it made. That distinction becomes painful when a long-running agent starts under a reviewed version and later receives an environment change or regenerated client library.

Sallyport keeps a Sessions journal and an Activity journal projected from one encrypted, hash-chained audit log, so an operator can inspect both the agent run and each HTTP or SSH action. Its offline sp audit verify check can verify the chain without access to the vault, which is useful when an upgrade review turns into an incident review.

Do not mistake tamper evidence for prevention. An intact audit trail can establish that a new endpoint was used. It cannot pull exported data back from a remote service. Keep sensitive actions behind credentials and approvals that fail before the request leaves the machine.

Approval must bind to a process, not a vague task

A human approval can stop an unreviewed upgrade only if the approval tells the human what executable is asking for authority. "Agent wants API access" is too little information when several local processes can speak the same protocol.

Bind session authorization to the code-signing authority of the requesting process where the operating system exposes it. This catches a common substitution failure: a trusted agent starts a session, then an untrusted helper or a copied binary tries to reuse the same credential route. A process identity does not prove every future request is wise, but it gives the operator a concrete object to approve or revoke.

Reserve per-call approval for credentials whose effect is inherently hard to confine, such as production deployment, account administration, or data export. Requiring a person to approve every harmless read simply trains them to click through cards. Approval fatigue is a design error, not a user flaw.

Sallyport uses a fixed three-control decision ladder: the locked vault denies all actions, a new agent process requests session authorization by default, and a per-key setting can require a separate approval for each use. That narrow model will not express every organizational rule, but it avoids burying authority changes inside a pile of policy syntax.

When an API upgrade changes a credential's effective scope, revoke the current session and force a fresh approval after the review. Do not let a session approved for yesterday's endpoint set quietly carry into tomorrow's broader one.

Make authority review a release gate

An API version upgrade should fail its release gate when a current credential gains an unexplained successful request, a denied request becomes permitted, or a response exposes a new identifier that enables a prohibited workflow.

Put the review in the same change record as dependency updates and generated-client changes. Record the old and new API selectors, provider release notes, the capability diff output, the credential classes tested, and the person who accepted each intentional difference. This is mundane work, which is why it gets skipped until the first strange audit entry.

Do not wait for a major API version. Trigger the review when the provider changes an API version, authentication service, OAuth application settings, generated SDK, discovery schema, default header, or scope definition. A change outside the URL can still alter the decision the remote server makes.

Start with the credential that would hurt most if it gained one extra route. Give it an isolated test account, write five allowed and denied requests, and run them against the proposed version. If you cannot describe why every success belongs to the agent's job, the integration is not ready for autonomous use.