Skip to main content

Scope an agent to least privilege

An autonomous agent should be able to reach exactly what its job requires — and nothing more. apistash is closed by default and lets you scope a credential precisely, so the key you hand an agent can be limited to a handful of tools, a subset of resources, specific prompts, and selected personal agent definitions. If the key leaks or the agent misbehaves, the blast radius is small and you revoke that one key.

One key per agent​

Give each agent or application its own API key (see Authentication → API keys). That way you can:

  • Revoke it alone — cut one agent's access without disrupting the others. Revocation blocks the next request.
  • Audit it alone — each key has its own activity history and a last_used_at timestamp.
  • Scope it alone — apply the policies below to exactly this agent's needs.

Restrict what it can reach​

A key needs the tools capability for governed tool calls, and resources, prompts, or agents for reading or using the corresponding content. These capabilities are independent. Governed content writes require tools, admission of the exact management tool, and permission for the action and target. The resources, prompts, and agents capabilities do not authorize writes and are not prerequisites for those writes.

On top of that, a personal key can carry policies that narrow it below your own access. They only ever tighten — a key can never reach more than you hold.

  • Tool policy — whitelist the exact tools the agent needs (or blacklist the few it shouldn't have). A restricted tool is hidden from tools/list and returns tool_not_permitted if it's called anyway.
  • Resource policy — limit which personal resources the key may read with path glob patterns.
  • Prompt policy — limit which platform and customer prompts the key may use. Platform prompts also need their MCP Settings allowlist; the effective Prompts capability is required.
  • Agent policy — after granting agents, limit which personal Agent definitions the key may assign, select, list, or read. bootstrap and agent_context are always callable system tools, while list_agents and get_agent are governed tools; all four still require agents and the matching Agent policy before delivering Agent content.

For example, a key that may only do arithmetic and read the time — the tools capability opens the surface, and the tool_policy narrows it to exactly two tools (listed by ID — the dashboard's key form picks them by name for you):

{
	"name": "scheduling-agent",
	"mcp_capabilities": ["tools"],
	"grants": [{ "scope": { "type": "personal" }, "permissions": [] }],
	"tool_policy": {
		"mode": "whitelist",
		"tools": ["<calculator-tool-id>", "<datetime-now-tool-id>"]
	}
}

Provided both tools are part of your account's tool selection (Settings → MCP Settings), that agent's tools/list returns those two plus the three fixed system tools — it can't see any other governed tool. The two controls stack rather than override: your selection sets what your credentials may reach at all, and a key's policy narrows it further. A tool that is in a key's whitelist but absent from your selection stays invisible.

See Tool policy, Resource policy, Prompt policy, and Agent policy for the full field reference.

In an organization​

When a key operates in an organization context, the per-key policies above are replaced by team bindings: mcp_capabilities still gates governed tool calls and content reading/use, while active team bindings decide which team-scoped content is reachable. Team writes additionally require admission of the management tool and the matching action permission for that bound team. The resources, prompts, and agents capabilities are not prerequisites for those writes. For Agent definitions, a member-attached credential can reach its personal-in-organization agents, agents owned by its bound teams, and organization-owned agents exposed organization-wide or admitted by at least one bound team's Agent policy. Team-owned agents remain visible through their ownership space rather than the organization-catalog policy. The independent agents capability gates assignment and Agent content. The bootstrap and agent_context system tools themselves remain callable without tools. A key can never request more capability than its creator holds. See how management and MCP access are separated.

Closed by default​

You never have to remove governed access an agent shouldn't have — it starts with none and sees only what its credential explicitly allows. tools/list, prompts/list, resources/list, list_agents, and Agent catalogs returned by Bootstrap are each filtered to the calling credential; the three system tools are the fixed authenticated baseline. See the access model.

tip

Pair a tightly-scoped key with a curated team catalogue so an agent sees a safe, vetted set of tools and nothing else.