Policies

A policy is a rule that decides whether a credential access is allowed. Every credential-use request — app or agent, retrieve or proxy — is evaluated against the relevant policies before the token is injected; if the policy denies, the call raises PolicyViolationError and the provider is never reached. One exception: a request-quota denial (the window’s limit is spent) raises QuotaExceededError instead, which carries a retry-after — the seconds until the window resets. The SDKs never auto-retry it.

Note

Policies never grant access — they only narrow it. Access is default-deny (zero-trust): a credential is already gated by ownership (the principal must own the grant), scope (the key must carry the capability), and the grant’s validity (not expired or revoked). With no policy set, access still requires all three. A policy is an additional layer that can only further restrict — deny a request, limit it to certain times or IPs, or require human approval — never widen what’s allowed.

Policies sit between who can call (the principal on the grant) and what they’re allowed to call right now. The principal binding answers “is Alice’s grant?”; the policy answers “is now a valid time, from a valid place, within rate?”

Where a policy lives

Layer	Set by	Example
Organization policy	An organization administrator in the developer portal	Require approval for sensitive operations in every application
Application policy	The operator in the developer portal or CLI	IP allowlist for every request in one application
Provider policy	The operator in the developer portal or CLI	Block sending through one provider
Agent policy	The operator in the developer portal or CLI	Rate limit one managed agent
Connection policy	The operator or end user	Restrict one OAuth or managed-secret grant
Account policy	The end user in the Wallet	Require approval across directly connected accounts
Constrained-client policy	The SDK caller	Create a sub-client whose requests carry an additional non-stored rule

Policies compose across the whole grant and delegation chain. A request that satisfies its connection policy but violates an application, agent, or account policy still fails. Grant expiry (TTL) and scopes are separate access ceilings — set when the grant or key is created, not authored as policy rules — displayed alongside the effective policy chain.

What policies can express

• Time-of-day windows — configurable day/time windows in a chosen timezone (e.g. business hours Mon–Fri, or an overnight maintenance window).
• IP allowlists — call only from listed IP addresses or CIDR ranges.
• Rate limits — cap calls per caller principal (agent when present, otherwise grant) per fixed window; over the limit, the call is denied with a retry-after until the window resets. This denial surfaces as QuotaExceededError, not PolicyViolationError.
• Attribute matches — deny requests matching metadata conditions: the HTTP method, the provider, the acting agent, the source IP, or the classified operation/family (“deny everything in the payment family”).
• Method/endpoint restrictions — allowlist the HTTP methods and provider API paths traffic may use (“GET only”, “/repos/** only”); enforced on proxied calls, so a restricted connection refuses raw-token retrieval.
• Approval requirements — route to a human-in-the-loop decision before executing, including multi-party (N-of-N) approval where distinct approver gates from applicable rules must each be approved, and parameter-conditional approvals (“only payments over $1,000 need sign-off”).
• Operation-level rules — bind a specific provider operation or a semantic family of operations (“everything that sends”, “everything that moves money”) from Alter’s reviewed operation catalog: “this agent may read Gmail but never send.”
• Parameter-level rules — conditions over what a request actually carries, canonicalized across provider formats: “may only email addresses at @acme.com”, “may not move more than $1,000.” A request the policy engine cannot fully classify is refused rather than guessed at.
• Redaction — strip named fields from a matching request before it reaches the provider (for example, the subject line of an outbound email), with the call refused if the redaction cannot be provably applied.
• Step-up authentication — require the acting end user to have signed in recently (“within the last 5 minutes”) for sensitive operations; a stale or unprovable session is refused with a clear re-authentication signal.

The last four are variants of one rule shape: a content-match rule binds a match — specific operations or semantic families from the cataloged operation catalog, optionally narrowed by conditions over the request’s canonicalized parameters — to one of three effects: deny (refuse the call), redact (strip named fields before the call is executed, refusing if the redaction cannot be provably applied), or step_up (require a sufficiently recent end-user sign-in). The SDKs expose typed builders for it (content_match_rule in Python, contentMatchRule in TypeScript), which validate the rule locally — effect-specific requirements included — before it is ever sent.

The developer portal and Wallet use the same structured editor and policy viewer. Owned rules show the complete definition: target, effect, operations, every parameter condition, status, source, and metadata. Inherited Wallet controls use the same viewer with disclosure-safe summaries that omit developer-only values. The CLI renders the same normalized explanation with alter policy rules get --output table; JSON remains the default for automation.

with_constraints (Python) and withConstraints (TypeScript) return constrained sub-clients. Every request made through that sub-client carries the additional rule; the original client remains unconstrained. Retain the original client for calls that should not carry the rule.

Fail-closed

If a policy cannot be evaluated (the policy engine is unreachable, the inputs are malformed, the policy version drifted), the request is denied. No call is made; no token leaves the vault. The error surfaces as PolicyViolationError with the failure reason on policy_error.

This is the opposite of fail-open systems where a missing policy is treated as “no rule, allow.” Alter treats a missing policy evaluator as “no decision, deny.”

Audit

Every policy decision (allow, deny, or error — error meaning the policy gate itself failed to evaluate and the request was denied fail-closed) emits an audit event with the deciding policy metadata and outcome. Projected parameter values are not logged. Denied calls never reach the provider and normally appear in the audit trail as first-class compliance evidence. If audit storage itself fails, the request result is preserved while critical gap telemetry and a fallback audit attempt make the missing record observable; see Security architecture.

What’s next

• Set policies — a step-by-step walkthrough for authoring each rule type from the dashboard, the CLI, and the SDK.
• Audit logs — where policy decisions are recorded.
• Add human-in-the-loop approvals — policy-driven approval flow.
• Security architecture — the policy engine in the larger picture.