> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity policies

> Scope which primitives, connections, and tools an identity's agents may use — enforced at the tool-call boundary.

<Info>Identity is **available now**, governed by the [policy](/docs/concepts/policies) layer.</Info>

Identity is where an agent touches the outside world, so it is where governance matters most. Every use of an email, phone, connection, or [vault](/docs/identity/vault) primitive passes through the same policy check as any other [tool call](/docs/concepts/policies) — evaluated before the action, and **fail-closed** if enforcement is unavailable.

## What a policy controls

A policy scopes which primitives are enabled, how connections are gated, and which actions require approval:

```jsonc theme={"system"}
{
  "primitives": { "email": true, "connections": true, "vault": true },
  "connections": {
    "mode": "allowlist",
    "toolkits": ["tracker", "chat"],
    "tools": { "tracker": { "disable": ["delete_project"] } }
  },
  "approval": { "connections": { "requiresApproval": true } }
}
```

## Two evaluation points

1. **Connect time.** Authorizing a new connection checks the toolkit against the `mode` and, for sensitive toolkits, may require human approval before the OAuth redirect.
2. **Call time.** Each `connection_call` re-checks the toolkit *and* the specific tool against `enable`/`disable` lists. A call outside the allowlist returns a typed `policy_denied` before any external request is made.

## Approval-gated by default

Some actions are sensitive enough to require human approval out of the box: **connecting** a new third-party app, **provisioning** a phone number, and **purchasing** a domain. When an action needs approval, the session emits a confirmation event and holds at storage cost until you respond — see [Policies](/docs/concepts/policies#responding-to-ask).

## Spend rules

An approval rule can be tied to a **threshold**: a primitive action whose quoted cost exceeds the configured amount forces approval even if the primitive is otherwise allowed. This composes with the pre-flight [budget gate](/docs/concepts/budgets) — the budget caps total spend; the policy governs *which* actions may spend at all.

## Configuration reference

<ParamField path="primitives" type="object">
  Which identity primitives are enabled: `email`, `phone`, `connections`, `vault`, `domains`. A disabled primitive is refused before any external request.
</ParamField>

<ParamField path="connections.mode" type="string" default="open">
  How third-party connections are scoped:
  <br />• `open` — any toolkit is allowed.
  <br />• `allowlist` — only listed toolkits are allowed.
  <br />• `blocklist` — every toolkit except the listed ones is allowed.
</ParamField>

<ParamField path="connections.toolkits" type="string[]">
  The toolkits the `allowlist` / `blocklist` applies to (e.g. `tracker`, `chat`).
</ParamField>

<ParamField path="connections.tools" type="object">
  Per-toolkit `enable` / `disable` lists for tool-level granularity within an allowed toolkit.
</ParamField>

<ParamField path="approval" type="object">
  Per-primitive approval rules — e.g. spend thresholds that force human approval, or specific sensitive actions that always require it.
</ParamField>

<Card title="Next: inbound events" icon="inbox">
  How inbound email and SMS wake a sleeping agent.
</Card>