Credentials and the broker
An agent can be allowed to call a tool and still need credentials to use the system behind it. For example, a policy might let a support agent read a Salesforce case, but Salesforce also needs to know which account is making the request.
Amelfi’s credential broker connects those two checks. The gateway authenticates the caller and evaluates policy, then obtains the approved upstream credential and applies it to the request. The MCP client receives the tool result without receiving the upstream secret.
Why credentials need their own rules
Section titled “Why credentials need their own rules”Giving every client the same API key makes it difficult to limit who can use that key, rotate it, or stop one agent without interrupting the others. Using a person’s credential for unattended automation creates a different problem, because the automation depends on that person’s account and permissions.
A credential mode specifies whose authority the upstream access represents. A credential binding records where that authority may be used and how the gateway obtains the credential. Policy decides whether the particular call is allowed. Each has a separate purpose, and a valid credential never overrides a policy deny.
Keep the two authentication steps separate. The token a client sends to Amelfi proves its identity to the gateway. The credential Amelfi sends to an upstream authenticates the permitted call to that system. Signing in to Amelfi does not automatically grant access to every upstream account.
How a binding connects identity to an upstream
Section titled “How a binding connects identity to an upstream”A binding includes its credential mode, allowed environment and targets, policy references, approval and lifecycle state, and credential source. For an agent-scoped binding, it also names the owning agent through agentSubject.
Secret references identify material in a configured secret store. OAuth configuration identifies an approved provider and constrains the intended upstream and scopes. Raw passwords, API keys, and tokens do not belong in the binding definition or tool arguments.
Identity travels. Secrets stay inside.
Scroll the diagram sideways to see the full flow →
Read the full explanation
- The client sends a verified identity and a requested tool. It does not send an upstream secret.
- The gateway evaluates policy and selects the allowed credential binding.
- The credential broker resolves the secret reference inside the trusted runtime boundary.
- The upstream receives the permitted credential. The client receives the tool result; audit receives metadata.
For a call that requires upstream credentials, the gateway must accept the caller’s identity, policy decision, binding, and credential resolution before it can execute the upstream request. An allowed call can therefore fail because its credential is unavailable or its binding is inactive. Public tools explicitly configured for credentialless access do not need an upstream credential.
Choose whose authority the call should use
Section titled “Choose whose authority the call should use”Choose the mode from the ownership requirement, then configure a supported credential mechanism for that mode and upstream.
| Mode | Access belongs to | Use it when |
|---|---|---|
service_account | A shared application or integration account | Several permitted callers should use the same upstream identity. |
user_delegated | A signed-in person | The upstream action should use that person’s consent and permissions. |
agent_scoped | One registered agent | An agent needs its own binding and independent revocation boundary. |
workload_mapped | A registered runtime workload | A job or service needs access based on verified infrastructure identity. |
The examples below illustrate the ownership choices. They do not imply that every upstream supports every credential mechanism.
Service account for shared integration access
Section titled “Service account for shared integration access”Use service_account when the organization owns an integration account that approved callers can share. For example, several support agents might read a common product catalog through one integration account. The gateway can apply different tool policies to those callers even though the catalog service sees the same account.
An administrator configures the integration credential source and limits the binding to the intended targets and environments. On a permitted call, the broker obtains that integration credential and applies it to the upstream request.
Several callers use one integration account
Scroll the diagram sideways to see the full flow →
Read the full explanation
- An approved caller requests a catalog tool using its own gateway identity.
- The gateway checks policy and selects the shared integration binding for this target.
- The broker resolves the integration credential from the configured secret source.
- The upstream authenticates the integration account. Gateway audit retains the original caller.
This mode supports shared automation without distributing the integration secret to each client. Its limitation is the shared upstream identity. Gateway audit can distinguish callers, but the upstream may attribute their actions to the same integration account. Rotating or revoking that shared upstream credential can affect every caller that depends on it.
User delegation for actions on a person’s behalf
Section titled “User delegation for actions on a person’s behalf”Use user_delegated when access should follow a person’s upstream permissions. For example, an assistant searching Alice’s private documents should use Alice’s authorized access, rather than an organization-wide account that can read everyone’s documents.
For an upstream OAuth user grant, an administrator configures the provider, target resource, and maximum scopes. Alice completes the provider’s authorization flow to grant access. During a later tool call, the gateway matches the signed-in person to the appropriate grant and uses the supported token lifecycle to obtain a usable upstream token. Alice does not need to complete an interactive login for every call.
A person grants access to their upstream account
Scroll the diagram sideways to see the full flow →
Read the full explanation
- Alice authorizes access with the configured upstream OAuth provider. This establishes her grant before tool use.
- Alice later requests a tool using her gateway identity. The gateway checks policy and her matching grant.
- The broker obtains a usable upstream token through the configured grant lifecycle and scope restrictions.
- The document service receives a token representing Alice and enforces her upstream permissions.
The upstream enforces the permissions associated with Alice’s token, while Amelfi independently enforces gateway policy. Missing consent, an unusable grant, or insufficient upstream permissions can prevent the action even when gateway policy allows the tool. The deployment must have the user-grant capability enabled and the provider configured.
A supported token-exchange configuration is another way to obtain a delegated upstream token. The ownership requirement remains the same: access must correspond to the resolved caller. A shared service-account credential is not a substitute for a missing user grant.
Agent scope for an independently governed agent
Section titled “Agent scope for an independently governed agent”Use agent_scoped when one registered agent needs a credential binding that other agents cannot reuse. For example, a contract-review agent may need Salesforce access that security can revoke without disabling an unrelated support agent.
An administrator registers and approves the agent, then creates a binding whose immutable agentSubject matches that agent. On each call, the gateway verifies the signed agent identity and checks the binding ownership alongside policy and environment restrictions. Only the matching approved agent can resolve the binding.
Only the owning agent can resolve its binding
Scroll the diagram sideways to see the full flow →
Read the full explanation
- The request carries the signed identity of the registered contract-review agent.
- The gateway checks agent eligibility, policy, environment, and the exact agentSubject on the binding.
- The broker obtains the credential for the matching agent binding. Another agent cannot reuse that binding.
- The broker applies the credential to the approved Salesforce request, retaining agent attribution in audit.
The binding provides an agent-specific access and revocation boundary. It does not automatically create a distinct account in the upstream or mint a new token for every call. If two bindings reference the same underlying upstream credential, that credential still has a shared rotation and exposure boundary. Use distinct upstream credentials when upstream-level separation is also required.
An agent can act for a human while keeping its own binding ownership. Policy and audit retain the agent and human delegator as separate identities. See Agent-scoped credentials for registration, identity claims, and enforcement outcomes.
Workload mapping for jobs and services
Section titled “Workload mapping for jobs and services”Use workload_mapped when access belongs to a registered runtime workload, such as a scheduled reconciliation service. The service should authenticate through the configured workload identity trust rather than depend on an employee being signed in.
The gateway resolves the verified workload identity and maps it to approved access. Policy and binding restrictions still determine which targets the workload may use. The broker then obtains the credential through the configured source, which may involve a supported token exchange.
A verified workload maps to approved access
Scroll the diagram sideways to see the full flow →
Read the full explanation
- A reconciliation job authenticates through the configured workload identity trust.
- The gateway resolves the registered workload and checks policy and its approved access mapping.
- The broker obtains the mapped credential through the configured source or supported token exchange.
- The approved upstream receives the credential. The job receives the tool result without the upstream secret.
This mode makes infrastructure identity the basis for credential access. An agent name in a request or an arbitrary workload header is not sufficient proof. The workload identity provider and mapping must be configured for the deployment. Choosing this mode alone does not configure cloud federation or guarantee that no stored secrets are needed.
Choose agent scope when the registered AI agent should own access across its executions. Choose workload mapping when the registered job or service should own access. Running an agent inside a container does not by itself decide the mode.
Ownership and credential mechanisms are separate choices
Section titled “Ownership and credential mechanisms are separate choices”The mode describes who owns access. The mechanism describes how the gateway obtains the credential. Depending on the binding and provider, that can mean resolving stored credential material, using an OAuth user grant, or exchanging a verified token for an upstream token with approved audience and scope restrictions.
For example, the user-grant configuration requires user_delegated. Supported token-exchange bindings can use user_delegated, agent_scoped, or workload_mapped. Those combinations require their own approved provider configuration; changing a mode field does not establish the necessary trust.
Rotate material or revoke access
Section titled “Rotate material or revoke access”Rotation replaces credential material while retaining the intended access relationship. Revocation removes authority, such as disabling an agent or revoking its binding. Deleting a user’s upstream consent is also different from rotating a shared integration key.
After a change, verify that the affected data planes have accepted the updated runtime configuration. Then check a new call and any relevant active session. An inactive binding must not continue authorizing calls through stale state. For a shared upstream secret, also consider other bindings that reference the same material.
Audit should identify the caller, binding, credential mode, policy decision, and upstream outcome without exposing secret values or tokens. When a call fails, check the identity, policy, binding state, target restrictions, and credential source before replacing the credential.
Continue with Create a credential binding to configure access, or Runtime configuration delivery to understand how approved changes reach data planes.
Implementation references
Section titled “Implementation references”Amelfi documentation · Space Grotesk / Geist Mono