How-to › Use AI to do the integration

How to give each agent tool the least privilege it needs#

Issue one credential per agent tool, scoped to the operations that tool performs, build one SDK client per tool, and read the 403 each tool gets outside its scope.

Audience
Platform team
Level
intermediate
Topic
Guard agents and add approvals
Languages
TypeScript and Python
Verified

Your agent has a tool that searches issues, one that files them, and one that purges spam. All three call the tracker through one client built with a full-access token. An issue title tells the model to delete everything, the search tool forwards the model’s method and path, and the tracker answers 204.

What you get

You will end up with one credential per tool, one SDK client per tool, and a table of what the server answers each credential for every operation. This is for you if you run an agent whose tools share an API.

Short answer

Give each agent tool its own credential, issued by the API’s provider for the operations that tool performs, and build one SDK client per tool from it. With sdkgen that is one client instance per tool, with the tool’s token as apikey and, as a hint, the rbac feature listing its operations. The provider’s refusal is the boundary, so prove it: call every operation with each tool’s credential and read the 403 for the ones outside its scope.

You will need

Node 22 or later, Python 3.11 or later for the Python side, an agent with at least two tools against the same API, and a provider that issues scoped credentials. Verified 2026-11-19 against Node 22.23.5, Python 3.13.18, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, and openapi-python-client 0.30.0. The sample’s clients were generated once from api.json, a five-operation Tracker document, and committed. Its provider is a local stand-in that issues four tokens, so no real key is involved.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
AWS STS session policyAWS APIs, where one role exists and each tool needs a narrower slice of itA policy document per tool passed at each AssumeRole, and sessions that expireThe API is not on AWS, or the role is narrow already
Fern client per tokenA Fern SDK, constructed once per tool with that tool’s tokenNo run-time hint, and a configured env default that every argument-free client sharesYou want the client to refuse out-of-scope calls itself
GitHub fine-grained personal access tokenGitHub’s API, one token per tool, limited to chosen repositories and permissionsTokens tied to the user who generated them, each with an expiry to trackThe tool acts for many users, where OAuth scopes fit
openapi-python-client, one client per toolA Python agent, where each tool imports only the operation modules it callsNothing in the client knows a scope, so only review and the server catch a wrong importYou want one model of the API across several languages
Per-tool wrapperAny client, when a tool should see two methods instead of the whole SDKCode per tool that hides methods, and stops nothing once a tool is handed the clientThe provider can already narrow the credential that far
sdkgen client per tool, with the rbac hintAn sdkgen SDK, one instance per tool with its token and its operation listA second table to keep, and no boundary at all without a scoped tokenThe provider’s scopes already match each tool’s operations

Voxgig maintains sdkgen. It is one of six options here, not the recommendation.

Two rows are boundaries, because the provider refuses: the GitHub token and the STS session, and with them any OAuth scope requested per tool. The other four decide how a client holds one credential per tool. A wrapper or a hint narrows what a tool tries, at the cost of a table the provider never sees.

List what each tool does, then issue a credential for that

Start from the operations, not from the token you have. tools.json is the whole table: three tools, the operations each performs, and the credential issued for it alone.

[
  { "name": "search_issues", "ops": ["issue.list", "issue.load"], "token": "tok-search" },
  { "name": "file_issue", "ops": ["issue.create"], "token": "tok-file" },
  { "name": "purge_spam", "ops": ["issue.remove"], "token": "tok-purge" }
]

The scope each operation needs is already in the OpenAPI document, in its security entry, so the scopes a tool needs follow from its row. Ask the provider for exactly those.

On GitHub that is a fine-grained token limited to one repository and permission.1 With OAuth it is a scope parameter per tool. On AWS it is AssumeRole with a session policy, whose permissions are the intersection of the role’s policy and the one you pass.

Build one client per tool

A client instance holds one credential, so tools that share an instance share a credential. Build one per tool:

export function clientFor(tool, base) {
  return new TrackerSDK({
    base,
    apikey: tool.token,
    // direct() is outside rbac, so the client refuses it unless a tool is given it on purpose.
    allow: { op: 'create,update,load,list,remove' },
    feature: { rbac: { active: true, deny: true, permissions: tool.ops, rules: RULES } },
  })
}

apikey is the boundary’s half: the tool’s own token. The rbac options are the hint’s half. Each operation requires a permission of its own name, and the tool holds the names in its row, so the client refuses every other operation before sending it. sdkgen’s feature reference says rbac gives fast, local failures and does not replace server-side authorization.

demo.mjs calls all five operations with each credential. It runs once with no hint, then once with it.

node demo.mjs
one credential per tool: what the tool does, what it needs, what its token was issued
  search_issues  list, load  needs issue:read    tok-search holds issue:read
  file_issue     create      needs issue:write   tok-file holds issue:write
  purge_spam     remove      needs issue:delete  tok-purge holds issue:delete

what the server answers each credential   list   load   create update remove
  search_issues  tok-search               200    200    403    403    403
  file_issue     tok-file                 403    403    201    200    403
  purge_spam     tok-purge                403    403    403    403    204
  any tool       tok-admin, one client    200    200    201    200    204

the same tokens behind the per-tool hint  list   load   create update remove
  search_issues  tok-search               200    200    unsent unsent unsent
  file_issue     tok-file                 unsent unsent 201    unsent unsent
  purge_spam     tok-purge                unsent unsent unsent unsent 204

The middle block is the one a reviewer should ask for. Every 403 is the provider refusing, and the last row is one full-access client shared by every tool, which is refused nothing. Separate tokens also let the server’s log say which tool made a call, and let you revoke one tool without stopping the other two.

file_issue shows where a scope ends. The tool only creates, but issue:write also covers update, so the server answers its token 200 there. The hint closes that gap in the third block, and only as a hint: anybody holding tok-file can still update.

Take the credential away from a hijacked tool

The search tool in the opening forwards a method and a path from the model’s arguments into direct(), the raw request call. hijack.mjs plants the delete and runs that tool three ways.

node hijack.mjs
the model asks search_issues for DELETE /issues/iss_1
  one full-access client shared by all   204                    iss_1 deleted
  the search tool holding its own token  403 needs issue:delete iss_1 kept, the tool gets an error
  its own token and the per-tool hint    not called             iss_1 kept, the tool gets an error

The flaw is the same in all three runs. What changes is the credential the flawed tool holds. The OWASP guidance on excessive agency asks for both halves: no open-ended extensions, and the minimum permissions for the ones that remain.2

Check it worked

Twelve Node tests pin the table: each credential’s five answers, with a 403 wherever its scope ends, the scopes each token was issued against the scopes its tool needs, and the hijack.

node --test tools.test.mjs
1..12
# tests 12
# suites 0
# pass 12
# fail 0
# cancelled 0
# skipped 0
# todo 0

The test to copy is the audit: it fails when a tool’s token holds a scope its operations do not need, which is how a full-access token gets into a tool unnoticed.

Do the same with Fern and with a generated Python client

Fern’s authentication page shows the generated client taking its credential in the constructor, as new Client({ token: "ey34..." }), so one client per tool is the same move. The same page lets x-fern-bearer name an env variable, and a client built with no arguments reads it. Every tool built that way shares one credential, so pass token explicitly.

Fern documents no run-time scope check. Its audiences feature, set in sdk-config.yml on the Enterprise plan, generates an SDK without the operations tagged only for other audiences. That is a per-tool wrapper made at build time.

The client openapi-python-client generates has no scope check either. Run on api.json, version 0.30.0 wrote an AuthenticatedClient class that takes a token, and one module per operation. A tool then is a client of its own plus the modules it imports:

from tracker_client import AuthenticatedClient
from tracker_client.api.default import get_issue, list_issues


def search_tool(base_url, token):
    """Build the tool around a client that no other tool holds."""
    client = AuthenticatedClient(base_url=base_url, token=token)
python3 demo.py
one AuthenticatedClient per tool          list   load   create update remove
  search_issues  tok-search               200    200    403    403    403
  file_issue     tok-file                 403    403    201    200    403
  purge_spam     tok-purge                403    403    403    403    204

search_tool(base_url, 'tok-search')()
  Crash on export
  Buy cheap watches
  Typo in the footer

The rows match the TypeScript client’s, because the answers come from the server. The generated package imports httpx2 and attrs, which npm ci installs into pydeps/ for this sample. A Python test reads search_tool.py and fails if it imports an operation outside the tool’s row.

python3 test_tools.py
ok each_credential_gets_a_403_outside_its_scope
ok one_client_per_tool_holds_one_token
ok the_search_tool_imports_only_the_operations_it_performs
ok the_search_tool_reads_and_its_token_cannot_delete
4 cases, 0 failures

When it goes wrong

Every tool can still delete. The tools were handed one module-level client, so they share its token whatever the table says. Build the client inside each tool’s setup, and assert on the token the server saw.

A tool gets a 403 on its own operation. The provider granted less than you asked for, or the document’s scope changed. Compare the scopes the token holds with the scopes its operations need, as the audit test does.

The hint passes a call that should have stopped. In sdkgen 4.44.3, rbac covers entity operations and not direct(). Leave direct out of allow.op unless a tool needs raw requests.

When not to do this

Do not treat sdkgen’s rbac hint as the control. It runs in the agent’s own process, and the third block of the demo comes out the same with a full-access token behind it. Scope the token first.

Do not mint a credential per tool when the provider cannot narrow one. Three copies of a full-access key are three places to leak it. Each of them would turn every cell of the middle block into a success.

Do not reach for a generator feature when the tool set is one Python process. With openapi-python-client, the operations a tool calls are its import lines, which a reviewer reads in a diff without learning a rule format.

Do not hand-write wrappers for every consumer when the split is fixed. A Fern audience produces the narrower SDK once, at build time, on its Enterprise plan.

Last verified

Verified 2026-11-19 against Node 22.23.5, Python 3.13.18, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, TypeScript 5.9.3, openapi-python-client 0.30.0, httpx2 2.16.2, and attrs 26.1.0. Every output block is what the command preceding it printed. The scaffold, the generation, and the openapi-python-client run are not repeated by the page’s checks: generate.sh ran them once, and their output is committed under generated/.

Fern was not run; its options come from its documentation, where the authentication page describes the OpenAPI extensions and the audiences page the current sdk-config.yml format. GitHub, AWS, and an OAuth server were not called: the provider is a local stand-in.

Footnotes

  1. GitHub’s token page carries one rule that needs no setting: as a security precaution, GitHub removes personal access tokens that have not been used in a year. A tool nobody calls for twelve months loses its credential without anybody revoking it. ↩︎ Back to text

  2. The entry is LLM06:2025 in the OWASP Top 10 for LLM Applications. Its prevention list has eight numbered items. The third says to avoid open-ended extensions, with running a shell command and fetching a URL as its examples, and the fourth says to minimize extension permissions. The seventh, complete mediation, asks that authorization be implemented in downstream systems, not left to a model to decide. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.