# 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.

Source: https://voxgig.com/howto/least-privilege-credentials-per-agent-tool

- Audience: platform-team
- Level: intermediate
- Languages: typescript, python
- Verified: 2026-11-19
- Published: 2026-11-19

## 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](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) | 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](https://buildwithfern.com/learn/api-definitions/openapi/authentication) | 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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) | 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](https://github.com/openapi-generators/openapi-python-client#what-you-get) | 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](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md#rbac) | 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](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.3) 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.

```json title="tools.json"
[
  { "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:

```js title="tools.mjs"
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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md#rbac)
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.

```bash
node demo.mjs
```

```text output
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.

```bash
node hijack.mjs
```

```text output
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.

```bash
node --test tools.test.mjs
```

```text output
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](https://buildwithfern.com/learn/api-definitions/openapi/authentication)
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:

```python title="search_tool.py"
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)
```

```bash
python3 demo.py
```

```text output
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.

```bash
python3 test_tools.py
```

```text output
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

- [Enforce scopes at the resource server, not in the client](/howto/enforce-scopes-at-the-resource-server)

- [Require human approval before an agent calls a delete tool](/howto/require-approval-before-a-delete-tool-call)

- [Sanitize tool results before they re-enter the prompt](/howto/sanitise-tool-results-before-reprompting)

- [Add a dry-run mode to an agent's write tools](/howto/add-dry-run-to-agent-write-tools)

- [Wire an API client into the OpenAI Agents SDK](/howto/wire-an-api-client-into-openai-agents-sdk)

- [Sandbox an agent's shell and code execution](/howto/sandbox-agent-shell-and-code-execution)

## 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.

[^1]: GitHub's
[token page](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
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.

[^2]: The entry is [LLM06:2025](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/) 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.