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

# Authorization & SPTs

> Explicit-deny authorization architecture with Skill Permission Tokens for capability-bounded agent operations.

# Authorization & Skill Permission Tokens

AgentVault employs a strict **explicit-deny** authorization architecture. By default, an enrolled agent cannot access any external system or perform destructive actions. Every privileged operation requires a grant.

***

## Capability Access Grants

To perform privileged actions, agents must hold **Capability Access Grants**, represented cryptographically as **Skill Permission Tokens (SPTs)**.

### SPT Structure

SPTs are signed JWTs that define exact functional boundaries:

```json theme={null}
{
  "iss": "agentvault",
  "sub": "did:hub:cortina",
  "aud": "api.agentvault.chat",
  "iat": 1710720000,
  "exp": 1711324800,
  "grants": {
    "capabilities": ["file_read", "api_call", "web_search"],
    "forbidden": ["process_spawn", "network_raw", "file_delete"],
    "rate_limits": {
      "api_call": { "max": 100, "window": "1h" },
      "web_search": { "max": 50, "window": "1h" }
    }
  },
  "trust_floor": 0.6,
  "policy_binding": "policy_uuid"
}
```

### Grant Lifecycle

<Steps>
  <Step title="Request">
    Agent or owner requests a capability grant via the dashboard or API.
  </Step>

  <Step title="Policy Evaluation">
    The 5-stage policy pipeline evaluates the request against active policies.
  </Step>

  <Step title="Issuance">
    If approved, an SPT is signed by the platform and bound to the agent's DID.
  </Step>

  <Step title="Enforcement">
    Every skill invocation is checked against active SPTs before execution.
  </Step>

  <Step title="Revocation">
    SPTs can be manually revoked or auto-revoked when trust scores drop below `trust_floor`.
  </Step>
</Steps>

***

## Automatic Revocation

SPTs are automatically revoked when:

1. **Trust score drops** below the SPT's `trust_floor` threshold
2. **Anomaly detected** — behavioral drift triggers a PSI alert above 0.25
3. **Policy violation** — the agent attempts a forbidden operation
4. **Expiration** — the SPT's `exp` claim passes

<Warning>
  Automatic revocation is immediate. The agent must request a new grant after the underlying issue is resolved.
</Warning>

***

## Policy Bindings

SPTs can be bound to specific policies for fine-grained control:

```bash theme={null}
# Bind a policy to an agent
POST /api/v1/policy-bindings
{
  "policy_id": "policy_uuid",
  "agent_id": "agent_uuid",
  "skill_name": "web_search",
  "active": true
}

# List active bindings
GET /api/v1/policy-bindings/{agent_id}

# Remove a binding
DELETE /api/v1/policy-bindings/{binding_id}
```

### 5-Stage Policy Pipeline

When a skill invocation occurs, the policy pipeline runs:

1. **Parse** — Extract action intent from the invocation request
2. **Validate** — Schema-validate the policy rules against the request
3. **Enforce** — Apply tool, model, and rate policies from active SPTs
4. **Log** — Emit an `av.policy.evaluate` telemetry span
5. **Report** — Aggregate policy metrics per agent and skill

***

## Enforcement Scopes

| Scope       | Description                                 | Example                                  |
| ----------- | ------------------------------------------- | ---------------------------------------- |
| **Tool**    | Allow/deny specific tool invocations        | Block `process_spawn`, allow `file_read` |
| **Model**   | Restrict which LLM models the agent can use | Allow only `gpt-4` and `claude-3`        |
| **Rate**    | Throttle invocation frequency               | Max 100 API calls per hour               |
| **Network** | Control egress destinations                 | Only allow `api.example.com:443`         |
| **Custom**  | Agent-defined policy rules                  | Custom business logic checks             |

### Violation Actions

| Action    | Behavior                                     |
| --------- | -------------------------------------------- |
| **Block** | Deny the invocation, return structured error |
| **Warn**  | Allow but log a warning and emit telemetry   |
| **Log**   | Silent logging — no agent-visible effect     |

***

## Integration with SKILL.md

Skills can declare required policies in their `agentVault` frontmatter:

```yaml theme={null}
---
name: web-research
agentVault:
  certification: certified
  requiredPolicies:
    - "network: agentvault"
    - "rate: standard"
  runtime:
    capabilities:
      - web_search
      - api_call
    forbidden:
      - process_spawn
      - file_delete
  model:
    allowed:
      - gpt-4
      - claude-3-opus
    default: gpt-4
---
```

When a skill with `requiredPolicies` is invoked, the policy enforcer verifies that all required policies are bound and active before allowing execution.

***

## MCP Policy Check

The `agentvault_check_policy` MCP tool allows agents to pre-flight policy checks before execution:

```json theme={null}
{
  "tool": "agentvault_check_policy",
  "input": {
    "skillName": "web-research",
    "toolName": "web_search",
    "model": "gpt-4"
  }
}
// Returns: { "allowed": true } or { "allowed": false, "violations": [...] }
```