Quick answer: Define which services, actions and resources an agent needs, then name the system that enforces each restriction. Gazebo can control retrieval of configured service keys. It cannot automatically limit which provider endpoints, environments or customer records a runtime accesses after receiving a key.
This is a permission-design worksheet. For the surrounding identity architecture, see IAM for AI agents; for hardening and negative tests, see least privilege for AI agents.
Define permission before choosing a token
An agent's task is a useful starting point, but a sentence such as “handle subscription inquiries” is not an access policy. Break it down:
| Question | Example answer | Possible enforcement |
|---|---|---|
| Which service? | Stripe, not GitHub | Retrieval grant and runtime/tool configuration |
| Which action? | Read subscriptions; create a billing portal session | Stripe key permissions and the tool performing the call |
| Which resource? | The authenticated customer's account | Application/provider authorization using trusted customer context |
| Which environment? | Test or staging, not production | Separate provider credentials and project/resource permissions |
| What evidence? | Retrieval decision and provider request outcome | Gazebo history plus provider/runtime records |
The entries are requirements to verify, not a Gazebo policy language. “Read-only” would be inaccurate for a workflow that creates a portal session: that action is a write, even if it does not change a subscription. Specify the allowed write and test that more sensitive writes are denied.
Distinguish the three enforcement layers
Service-key retrieval. A Gazebo profile can permit or deny retrieval for configured services and declared HTTP methods; OAuth connections require explicit approval of named keys. The actual key is returned on success. The declared method describes the release request, not proof of the method used in a later provider call.
Provider permissions. A restricted key or workload identity determines which provider operations are authorized. Prefer the narrowest usable provider capability. If several Gazebo profiles receive the same underlying key, they receive its same provider permissions; changing a profile does not rewrite the key.
Resource and task authorization. A customer ID, deployment target or approval may require a check at the application or provider executing the operation. Do not trust a customer ID supplied by an untrusted agent as proof of tenancy. Bind the request to an authenticated customer and enforce the relationship at the data-access boundary.
Not every service supports each dimension in the same way. If the necessary restriction is unavailable, change the workflow, use a different provider credential or place a separately designed execution control in the path. Calling credential retrieval a broker does not make it that execution control.
Stripe example: subscription support
Suppose an agent needs to inspect a subscription and create a customer portal session. Stripe restricted API keys let an operator select resource-level Read, Write or None permissions. Create and test an appropriately restricted key against the actual endpoints the workflow uses; do not assume a conceptual label such as billing_portal.sessions:write is the exact dashboard setting.
The desired test is concrete: the agent can retrieve the intended key and complete the inquiry, but the provider denies an attempt to issue a refund or make a charge with that key. If the workflow serves a specific tenant, the application must also validate the authenticated customer's relationship to any requested subscription. The retrieval log cannot establish which customer record Stripe returned.
GitHub example: PR triage
For an agent that reads pull requests, applies labels and requests reviewers, select the repositories and permissions needed by the actual GitHub endpoints. Fine-grained personal access tokens offer repository and permission selection, but their coverage has limitations; a GitHub App or another appropriate identity may fit better. Do not infer from a friendly label such as pull_requests:write that it alone permits every labeling or reviewer action.
Test read, label and reviewer operations in a test repository. Also test that the chosen identity cannot change repository settings or push code if those actions are outside the task. Provider and tool logs—not Gazebo's retrieval history—are needed to attribute later GitHub actions.
Vercel example: one deployment project
Vercel documents full-account, team and project-scoped API tokens. For a deployment limited to one project, check whether a project-scoped token supports the actual resources and API calls needed. Project scope is not a general-purpose guarantee that the token can create deployments but cannot perform any other operation in that project.
Use separate credentials for staging and production where the deployment design permits it. If the native token's permissions remain too broad, a Gazebo retrieval profile alone will not block an already delivered key from calling other Vercel endpoints.
Temporary elevation and reviews
For an exceptional task, grant only the needed access for an appropriate period and record its owner. Expiring or revoking a Gazebo retrieval identity stops future retrieval through that identity. It does not expire a provider key already returned or terminate a runtime session holding that key. Narrow or expire the provider-side access too when required; use an operation-level approval at the executing tool if the action itself needs a second decision.
During review, inventory the identities, provider keys and other credential paths each agent can use. Compare the intended permission matrix with provider settings and actual allowed/denied tests. Investigate a denied retrieval before widening a grant. Choose the review cadence based on risk and activity; a static age threshold is not evidence that a credential is unsafe.
Named profiles and retrieval history can support access reviews, but they are not automatic SOC 2, HIPAA or ISO 27001 compliance. They do not prove downstream record access or that an operation was approved. Document the owner, task, enforcement point, evidence source and residual access for each grant. See the access lifecycle guide for offboarding and HIPAA and AI agents for compliance boundaries.