Agent Policy (Capabilities) & Secret Constraints

To ensure fine-grained control and zero-trust security when deploying AI agents, AgentSecrets implements two key enforcement layers on top of your credentials: Agent Policies (Capabilities) and Secret Constraints.

Agent Policies (Capabilities)

Agent Policies allow you to bind permissions directly to an agent identity. They specify which secrets a given agent token (agt_...) can inject.

By default, an agent has access to all secrets within its project/workspace scope. Once you configure a policy, access is restricted to the whitelist or blacklist you define.

Commands

Get Agent Policy

To inspect the policy configured for an agent:

agentsecrets agent policy get <agent-name>

Set Agent Policy

To restrict an agent to specific keys (whitelisting) using a comma-separated list or repeatable flags:

# Comma-separated list
agentsecrets agent policy set <agent-name> --allow GITHUB_TOKEN,SERP_KEY

# Repeatable flags
agentsecrets agent policy set <agent-name> --allow GITHUB_TOKEN --allow SERP_KEY

To block an agent from accessing specific sensitive keys (blacklisting):

# Comma-separated list
agentsecrets agent policy set <agent-name> --deny STRIPE_SECRET_KEY,AWS_SECRET_ACCESS_KEY

# Repeatable flags
agentsecrets agent policy set <agent-name> --deny STRIPE_SECRET_KEY --deny AWS_SECRET_ACCESS_KEY

• Setting agent policies is a sensitive administrative action. The CLI will prompt you for your workspace/project password to authenticate the changes.
• Secrets must exist locally or remotely in the project before you can bind them to an agent policy. Providing a key that does not exist will fail the command with a SEC-404 validation error.

Secret Constraints

Secret Constraints define rules bound to the secret key itself, regardless of which agent is requesting it. They restrict the target domains and HTTP methods that are permitted to receive the credential.

Structure of a Constraint

A constraint rule dictates:

1. Target Domains: A list of domains where the key can be sent (e.g. api.stripe.com). If specified, sending this key to any other domain is blocked.
2. Method Actions: Actions mapped to HTTP methods (GET, POST, etc.):
   • allow: Seamless injection.
   • deny: Hard block.
   • request_permission: Runtime developer approval required.

Commands

View Secret Policy

To inspect the current policy/constraints of a secret key:

agentsecrets secrets policy get <KEY>

Set Secret Policy

To bind target constraints to a secret:

agentsecrets secrets policy set <KEY> --domains api.stripe.com --methods GET,POST --action request_permission

Alternatively, to bind domain-specific method rules:

agentsecrets secrets policy set <KEY> --rule api.stripe.com:GET=allow,POST=request_permission

Clear Secret Policy

To remove all target constraints from a secret:

agentsecrets secrets policy delete <KEY>

Modifying secret policies requires password verification.

Runtime Approvals

If a secret constraint specifies request_permission for an HTTP method and domain, the proxy will temporarily pause the outgoing request and return a 403 Forbidden response to the agent, specifying that developer approval is required.

To authorize the request session-wide (until the proxy is restarted), run the approval command in your developer terminal:

agentsecrets proxy approve <KEY> <METHOD> <DOMAIN>

Once approved, the agent can successfully re-run the request and the proxy will inject the secret.