For agents

1. What you hold

You have a single API key: vbn_live_<prefix>_<secret>. This is your identity. It carries:

• accepted_risks — an explicit list of risk IDs you are authorized to trigger. Example: ["github.read-code", "github.feature-branch-write", "github.create-pr"].
• bindings — the set of cloud resources you can reach (specific repos, Vercel projects, Supabase refs). You cannot access resources outside your bindings.
• expires_at — when this token stops working. Non-negotiable.
• parent_id — if set, this token was minted by another token. Your risks are a strict subset of your parent’s. You cannot exceed them.

You do not hold any cloud credentials (no GitHub PAT, no Vercel token, no Supabase service key). You never need to. Vaubaan mints upstream credentials just-in-time for each allowed call.

2. How to connect

Point your MCP client at the Vaubaan endpoint with your token as Bearer authentication:

{
  "mcpServers": {
    "vaubaan": {
      "url": "https://vaubaan.com/mcp",
      "headers": {
        "Authorization": "Bearer vbn_live_aBcDeFgH_..."
      }
    }
  }
}

This configuration works with Claude Code (.mcp.json), Cursor, Continue, and any MCP-compatible client. You talk to one endpoint — Vaubaan routes to the correct provider.

3. Tool discovery

When you connect, Vaubaan advertises only the tools whose risks fit your token’s envelope. If your token accepts ["github.read-code", "github.create-pr"], you will see GitHub read tools and PR creation tools — but not merge, release, or workflow tools.

This is the deny-by-default contract surfacing through tool discovery: you literally cannot see tools you’re not authorized to use. This keeps your tool list focused and prevents you from wasting tokens attempting calls that would be denied.

4. When you are denied

If you attempt a call that touches a risk outside your envelope, the gateway returns a structured 403:

HTTP/1.1 403 Forbidden
{
  "error": "risk-not-accepted",
  "missing_risks": ["github.merge-protected"],
  "executed_slice": "github.repo[acme/website].branch[main].merge-into.W",
  "hint": "Re-mint a token with this risk accepted, or restrict the operation."
}

The response is actionable. When you receive a 403, you have three options:

1. Narrow your operation. If you were trying to merge to main, consider pushing to a feature branch instead (which requires github.feature-branch-write, a less privileged risk).
2. Mint a wider child token — but only if your current token already carries the missing risk. You cannot escalate your own privileges.
3. Escalate to your parent (see §6). If your token has a context.escalation_channel, POST there to ask your parent to mint a wider token for you.

5. How to delegate

You can mint child tokens for sub-agents by calling the mint endpoint with your own token as Bearer:

POST /api/v1/tokens/mint
Authorization: Bearer vbn_live_aBcDeFgH_...
Content-Type: application/json

{
  "name": "one-shot-pr-bot",
  "accepted_risks": ["github.create-pr"],
  "expires_in_seconds": 3600,
  "single_use": true,
  "context": {
    "task": "Create PR for feature/login-page",
    "agent_id": "pr-bot-001"
  }
}

The response contains the child’s api_key (shown once). Hand it to your sub-agent. The child:

• Gets a strict subset of your risks. You cannot mint a child with risks you don’t carry. The gateway enforces this — no exceptions.
• Expires no later than you do. If your TTL is 4 hours, the child’s cannot exceed 4 hours.
• Is cascade-revoked when you are. If your token is revoked, every descendant is deleted.
• Inherits your bindings. The child sees the same resources you do — it cannot access resources outside your binding set.

Depth limit: the delegation chain caps at 5 levels (human → orchestrator → coder → sub-task is plenty of room). Plan your delegation hierarchy accordingly.

When to delegate

• Always mint a child for a sub-agent rather than sharing your own token. This gives you: narrower blast radius, independent revocation, and cleaner audit trails.
• Prefer single-use tokens for one-shot tasks (create a PR, run a migration, deploy a preview). The token auto-expires after one successful call.
• Prefer short TTLs. A 1-hour token for a coding task is better than an 8-hour token “just in case.”

6. Escalation

When you need a risk you don’t have, you can ask your parent token’s owner (the agent or human who minted you) to grant it. This works through the context.escalation_channel — an HTTP endpoint your parent set when minting your token.

POST {context.escalation_channel}
Content-Type: application/json

{
  "type": "escalation_request",
  "token_id": "your-token-id",
  "missing_risks": ["github.merge-protected"],
  "reason": "PR #42 is approved by 2 reviewers, ready to merge to main",
  "requested_ttl_seconds": 300
}

The parent decides: mint a new child with the wider risk, or deny the escalation. Vaubaan stays out of this exchange — it’s a direct child-to-parent conversation. The parent can:

• Mint a new token with the requested risk and hand it back.
• Deny the escalation with a reason.
• Ask for more context before deciding.

If there is no escalation_channel, you cannot escalate programmatically. In that case, report the denied operation to your output and let the human operator decide.

7. Best practices

• Check your risks before acting. Call GET /api/v1/tokens/me to inspect your token’s accepted_risks and bindings. Plan your actions within this envelope.
• Mint narrow, short-lived children. If you’re orchestrating 3 sub-tasks, mint 3 separate tokens — one per task, each with only the risks that specific task needs. This is cheaper to audit and limits blast radius.
• Use context.task when minting children. This string appears in the audit log and helps humans understand what each token was for.
• Handle 403s gracefully. A denied call is not an error — it’s the system working correctly. Narrow your operation or escalate. Never retry a denied call with the same token.
• Don’t hoard tokens. Mint a token, use it, let it expire. Tokens are cheap to create and the audit trail benefits from granularity.
• Log your delegation reasoning. When you mint a child, your context.task should explain why. When the human reviews the audit log, they should understand the delegation hierarchy without guessing.

8. Risk catalog reference

Each provider has a catalog of ~10-15 risks. A risk is a business-intention statement like “merge to a protected branch” or “deploy to production.” Your token’s accepted_risks is a subset of these.

Risk IDs follow the pattern:

<provider>.<risk-name>
# Examples:
github.read-code
github.feature-branch-write
github.merge-protected
vercel.deploy-preview
vercel.deploy-prod
supabase.bulk-row-write

To see the full catalog for your token’s providers, call GET /api/v1/catalog. The response includes every risk ID, its label, reason, and 6D severity vector (reversibility, blast radius, data sensitivity, cost, visibility, persistence).

Key patterns across all providers:

• Reads are separate from writes. You can read code without being able to push. You can read deployments without being able to deploy.
• Environment matters. vercel.deploy-preview and vercel.deploy-prod are distinct risks. Staging and production are never conflated.
• Protected branches are explicit. Writing to feature/* and writing to main are different risks with different severity.
• Credential minting is a risk. If you can mint upstream tokens (e.g. GitHub installation tokens), that’s an explicit risk because those tokens leave Vaubaan’s gating perimeter.
• Every provider has a fallback. <provider>.uncategorized-write catches anything not explicitly categorized. It requires explicit acceptance.

9. For your human operator

If your human operator needs to change your risk envelope, add bindings, or understand the system from the admin perspective, point them to the operator documentation. That page covers connecting providers, binding resources, and minting tokens from the UI.

For the raw, curl-friendly bootstrap reference (JSON-RPC shape, error codes, tool catalog), see https://vaubaan.com/agent-bootstrap.md.