Skip to main content

Access Model

Every agent connects to apistash with a credential — an API key or an OAuth token (see Authentication). apistash gives you a handful of independent controls over what each credential can reach, so you can hand an agent exactly the access it needs and nothing more.

You don't have to use all of them. This page explains what each control is for and what you gain from it.

Category access​

Choose whether a credential may call governed tools, read prompts and resources, or use agent definitions. Each usage capability is granted independently. Agent definitions are delivered through system tools rather than a fourth native MCP protocol surface.

What you gain: keep a credential's job narrow. A read-only research agent can be given resources and prompts but no ability to run governed tools; a task-runner can be given tools but no ability to read your resources. Every usage category is explicit. Tools and Agents never imply one another.

setup, bootstrap, and agent_context are authenticated system tools. They do not require Tools and do not appear in tool selections or policies. Selecting or returning Agent content through bootstrap or agent_context separately needs Agents and the applicable Agent visibility controls.

setup returns instructions for the local agent to install, repair, or update task-start behavior. After a general setup request, the local agent also offers optional guided content onboarding. The system tool writes no customer content; confirmed writes still require admitted management tools and the applicable permissions.

Platform prompts, such as apistash/agent-doctor, require effective Prompts capability, their platform allowlist, and the key or team Prompt policy. Fetching the Doctor requires no Tools or Agents capability. To carry out its audit, the connected model additionally needs Agents, Tools, and admission of apistash/get_agent; the inventory mode also needs apistash/list_agents. Explicit selections work without list admission. Bootstrap's independent Agent discovery remains available without Tools. The audit guide shows a restricted credential and explains the boundary of its read-only guarantee.

The tool allowlist​

Choose exactly which governed built-in tools a credential may call, out of the configurable catalogue.

What you gain:

  • Lower cost and less confusion — the agent only sees the handful of tools it actually needs, which keeps its context small and stops it reaching for the wrong tool.
  • Blast-radius control — if a key leaks, it can call only the governed tools on its allowlist, in addition to the fixed authenticated system tools.

The allowlist is opt-in: until you add tools to it, the credential can call none of the governed built-in tools. The authenticated system tools remain available. This is the safe default, not a mistake — and it is the first governed-tool setting to configure on a new account. You choose the selection under Settings → MCP Settings in the dashboard (an organization has its own, under the organization's settings); see Quick Start.

Platform prompts have their own selection in the same MCP Settings page and follow the same allowlist and key/team policy stages. Their allowlist starts empty too. The independent New platform tools and New platform prompts defaults add only future publications to the matching allowlist; they do not backfill existing items or mark organization items org-wide.

Turning items on and off​

Every resource and custom tool has an on/off switch.

What you gain: publish or retract an item without deleting it. Build a connector or a resource, keep its definition, and flip whether agents can see and use it — handy for staging something before rollout, or pulling it during an incident.

Ownership: personal, team, and organization​

Every customer prompt, resource, custom tool, and agent definition has one owner, which sets its ownership space:

  • Personal items stay yours.
  • Team items stay within that team.
  • Organization items form the shared catalogue.

What you gain: one hosted server serves many people and teams without anything leaking across boundaries — your personal experiments stay private, each team keeps its own space, and the org catalogue is the shared library. See Organizations & Teams.

Org-wide items and team bindings​

Inside an organization, two levers decide who reaches the shared catalogue:

  • Mark a catalogue item org-wide to include it in the organization-wide set, independent of team bindings.
  • Bind a credential to one or more teams to connect it to those teams' curated sets.

Neither lever opens a category. A credential sees an item only in a category you granted; org-wide designation and team bindings decide which items it reaches there.

What you gain: different agents can carry different toolsets from the same server — your support agent and your billing agent each get their own team's tools. Team bindings are additive, so a credential bound to two teams gets the combination of both — useful for an agent that legitimately spans teams.

warning

A credential with no team bindings can reach no team-scoped items; within the shared catalogue, it can reach only org-wide items. If an agent isn't seeing a team's tools or resources, check that its credential is bound to that team.

Per-credential fine-tuning​

On top of everything above, a standalone personal API key can restrict itself further — allow just a named set of tools or agent definitions, or block a few — independent of what the rest of your team can do. Its Agent policy is applied only after Agents is granted. Personal OAuth has no per-connection policy and follows personal ownership. Organization keys and organization OAuth connections use organization/team exposure instead of a per-credential Agent policy.

What you gain: tighten one agent without touching anyone else. For example, a CI key allowed only the three tools your pipeline uses.

Management access is separate. Governed MCP writes require Tools, admission of the exact management tool, and permission for the action and target. Prompts, Resources, and Agents capabilities govern reading/use; they neither authorize writes nor are prerequisites for those writes. See management permissions. MCP list_agents and get_agent are usage views, so their content reads require Agents rather than an inventory-view permission.

Interactive logins can't drive agents​

Your dashboard login — the browser session you use to sign in — cannot connect to the MCP endpoint. Agent access always requires a purpose-issued credential (an API key or an OAuth token).

What you gain: a stolen browser session can never be turned into agent tool access, and you can scope and revoke agent credentials independently of your own login.

Putting it together — an example​

You issue an organization API key for a customer-support agent:

  • You bind it to the Support team and grant it the tools and resources surfaces (not prompts).
  • The Support team's tools are limited to search_tickets, create_ticket, and refund.
  • Your org catalogue has a company_handbook resource marked org-wide; the Support team has its own kb_articles resource.

What the agent sees:

  • Tools: the system tools plus search_tickets, create_ticket, and refund — and no other governed tools.
  • Resources: company_handbook (org-wide) and kb_articles (owned by its team) — both on the resources surface, which you granted. The Billing team's resources stay invisible; a switched-off resource is invisible to everyone.
  • Prompts: none — you didn't grant that surface.
  • No agent definitions — you did not grant Agents, even though Tools is present.

Now unbind the key from all teams: it can call no team tools and sees only company_handbook — because a credential with no team bindings reaches only org-wide items.

Configuring access​

You set these controls when you create credentials and manage teams — see Authentication for API keys and OAuth. Teams and org-wide items are managed in the dashboard.