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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| AWS STS session policy | AWS APIs, where one role exists and each tool needs a narrower slice of it | A policy document per tool passed at each AssumeRole, and sessions that expire | The API is not on AWS, or the role is narrow already |
| Fern client per token | A Fern SDK, constructed once per tool with that tool’s token | No run-time hint, and a configured env default that every argument-free client shares | You want the client to refuse out-of-scope calls itself |
| GitHub fine-grained personal access token | GitHub’s API, one token per tool, limited to chosen repositories and permissions | Tokens tied to the user who generated them, each with an expiry to track | The tool acts for many users, where OAuth scopes fit |
openapi-python-client, one client per tool | A Python agent, where each tool imports only the operation modules it calls | Nothing in the client knows a scope, so only review and the server catch a wrong import | You want one model of the API across several languages |
| Per-tool wrapper | Any client, when a tool should see two methods instead of the whole SDK | Code per tool that hides methods, and stops nothing once a tool is handed the client | The provider can already narrow the credential that far |
| sdkgen client per tool, with the rbac hint | An sdkgen SDK, one instance per tool with its token and its operation list | A second table to keep, and no boundary at all without a scoped token | The 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.
Related how-tos
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
-
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
-
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