---
name: sumvin
description: Use when helping agents act on behalf of users with verified identity and signed spending limits. Reach for this skill when agents need to request Stamped Mandates, create errands (purchases), verify identity, manage agent identities, or check mandates presented by other agents. Use for any task involving agent authorization, identity verification, spending limits, or purchase workflows.
metadata:
    mintlify-proj: sumvin
    version: "1.0"
---

# Sumvin Skill

## Product summary

Sumvin is an identity and authorization platform for agents. It lets agents prove they act for a verified person and stay within signed spending limits. Agents connect via the MCP connector (recommended) at `https://mcp.sumvin.com/mcp` or use the CLI (`sumvin` command). The core objects are: **Sigil** (verified identity), **Agent Identity** (per-connection proof), **Stamped Mandate** (signed authorization), and **Errand** (purchase task). Primary docs: https://docs.sumvin.com. Key CLI commands: `sumvin login`, `sumvin kyc`, `sumvin pint` (mandates), `sumvin errand`. SDK available at `@sumvin/sdk` on npm.

## When to use

Reach for this skill when:
- An agent needs to request a Stamped Mandate (spending limit) from a user
- An agent is creating or managing errands (purchases) within a mandate
- A user needs to verify their identity to unlock Sumvin features
- You're checking whether a Stamped Mandate presented by another agent is valid
- A user wants to revoke a mandate or disconnect an agent
- You're reading an agent's identity or Sigil status
- You're building a terminal agent or custom tool using the CLI or SDK
- A user needs to set spending limits, conditions, or expiry dates on a mandate

Do not use this skill for: account creation (users self-serve), payment processing (Envoy handles this), or features not yet in preview.

## Quick reference

### MCP connector tools (for agents)

| Tool | Type | Purpose |
|---|---|---|
| `signup_start` | Write | Get sign-up link (no account needed) |
| `kyc_start` | Write | Start identity verification |
| `onboarding_status` | Read | Check setup progress |
| `sigil_show` | Read | Show verified identity |
| `agent_identity_show` | Read | Show this connection's identity |
| `mandate_request` | Write | Ask user to sign spending limit |
| `mandate_status` | Read | Check if user approved mandate |
| `mandate_verify` | Read | Verify mandate from another agent |
| `mandate_capacity_query` | Read | Check remaining spend on mandate |
| `pint_query` | Read | List user's mandates |
| `pint_revoke` | Write | Revoke a mandate |
| `errand_create` | Write | Start a purchase task |
| `errand_action` | Write | Answer errand questions or cancel |
| `errand_query` | Read | Check errand status |
| `errand_events_query` | Read | Read errand history |

### CLI commands

```bash
sumvin login                          # Sign in with device code
sumvin logout                         # Sign out and revoke token
sumvin whoami                         # Check current session
sumvin kyc start                      # Start identity verification
sumvin kyc status                     # Check verification progress
sumvin pint create --scope <s> ...    # Create Stamped Mandate
sumvin pint list                      # List mandates
sumvin pint revoke <id>               # Revoke a mandate
sumvin errand create <description>    # Start an errand
sumvin errand list                    # List errands
sumvin errand get <id>                # Check errand status
sumvin errand events <id>             # Read errand history
sumvin errand approve <id>            # Approve a purchase
sumvin errand reject <id>             # Decline a purchase
sumvin errand clarify <id> <answer>   # Answer errand question
sumvin errand cancel <id>             # Cancel an errand
```

### Mandate scopes (common)

| Scope | Grants | Requires verified Sigil |
|---|---|---|
| `sr:us:pint:sigil:proof_of_personhood` | Prove person is real | Yes |
| `sr:us:pint:sigil:age_over_18` | Attest age ≥18 | Yes |
| `sr:us:pint:spend:visa_checkout` | Card checkout (requires `max` and `currency`) | Yes |
| `sr:us:pint:errand:search` | Start errand search (requires `time`) | Yes |
| `sr:us:pint:errand:manage` | Answer questions, cancel errand | No |
| `sr:us:pint:mandates:propose` | Draft mandate for user to sign | No |
| `sr:us:pint:pints:read` | Read user's signed mandates | No |
| `sr:us:pint:pints:revoke` | Revoke a mandate | No |

### Mandate states

| State | Meaning |
|---|---|
| `proposed` | Waiting for user approval |
| `stamped` | User signed it; now active |
| `declined` | User refused or withdrew request |
| `expired` | Request lapsed unanswered |

### Errand states

| State | Meaning |
|---|---|
| `qualifying` | Agent understanding the request |
| `searching` | Looking for options |
| `validating` | Checking option against request |
| `pending_clarification` | Agent has a question for user |
| `pending_approval` | Ready to buy; needs user approval |
| `approved` | User approved; proceeding |
| `monitoring` | Waiting for conditions (price, etc.) |
| `executing` | Purchase in progress |
| `completed` | Done |
| `failed` | Couldn't complete |
| `expired` | Time ran out |
| `cancelled` | Stopped by user or revoked mandate |

## Decision guidance

### When to use MCP connector vs CLI

| Scenario | Use MCP | Use CLI |
|---|---|---|
| Agent in Claude, ChatGPT, or other client | ✓ | |
| Building custom terminal agent | | ✓ |
| Experimenting or testing | | ✓ |
| Production agent integration | ✓ | |
| Scripting automation | | ✓ |

### When to request mandate vs pre-authorize

| Approach | When to use |
|---|---|
| **Approve each purchase** (default) | One-off purchases; user wants to review each time |
| **Pre-authorized** | Repeat errands (e.g., "reorder coffee weekly"); user sets conditions once |

### When to check mandate: offline vs online

| Check | When to use |
|---|---|
| **Offline** (JWT verification) | Fast, no API key needed; checks token is genuine and unexpired |
| **Online** (`mandate_verify` tool) | Confirms mandate still active; catches revocations in real time |

## Workflow

### For agents requesting a mandate

1. **Determine what you need.** Identify the scopes (e.g., `spend:visa_checkout`, `errand:search`) and parameters (max amount, currency, expiry).
2. **Call `mandate_request`.** Pass scopes, a human-readable statement, and optional limits (max-amount, expiry window like `24h` or `7d`).
3. **Hand user the approval link.** The tool returns a link; user opens it in their own browser.
4. **Poll `mandate_status`.** Check periodically if user approved, declined, or let it expire. No notification is sent.
5. **Use the mandate token.** Once stamped, the token proves the user authorized those scopes and limits.

### For agents creating an errand

1. **Start with `errand_create`.** Pass the user's request in their own words (e.g., "reorder my usual coffee beans").
2. **Handle `pending_clarification`.** If the errand needs more detail, it waits. Call `errand_action` with the user's answer.
3. **Wait for `pending_approval`.** When a purchase is ready, the errand stops. User must approve it themselves (coming soon in connector; available now in CLI).
4. **Monitor with `errand_query` and `errand_events_query`.** Check status and history. Errand moves through states: qualifying → searching → validating → pending_clarification/pending_approval → approved → executing → completed/failed/cancelled.
5. **Cancel if needed.** Call `errand_action` with cancel instruction if user changes mind.

### For verifiers checking a mandate

1. **Receive the mandate token** from an agent.
2. **Verify offline (recommended).** Decode the JWT, check signature against Sumvin's published keys, verify expiry and hostname match. No API key needed.
3. **Verify online if needed.** Call `mandate_verify` with the token to confirm it hasn't been revoked since issuance.
4. **Read the scopes.** Parse what the mandate permits; never trust the agent's description.
5. **Act only within scope.** Refuse any request outside what the mandate grants.

### For users revoking access

1. **To revoke a mandate:** Call `pint_revoke` with the mandate ID (find it with `pint_query`). Revocation is permanent; anything using it stops immediately.
2. **To disconnect an agent:** Remove the Sumvin connector from that agent's settings (Claude, ChatGPT, etc.). Mandates it requested stay valid until revoked separately.
3. **To sign out CLI:** Run `sumvin logout`. Revokes the token on the server and removes it locally.

## Common gotchas

- **Never give an unattended agent `--yes` flag.** The `--yes` flag on CLI commands bypasses prompts. Only use it in attended scripts where a human is watching.
- **Disconnecting an agent doesn't revoke mandates.** Removing the connector stops the agent from acting, but mandates it requested stay valid. Revoke them separately with `pint_revoke`.
- **Mandate approval is always manual.** An agent can request a mandate; only the user can approve it with their passkey in their own browser. No agent can approve on behalf of a user.
- **Errand approval from connector is coming soon.** Until payments ship, errands created via MCP stay at `pending_approval` and can't be approved from the connector. Use the CLI or wait for the feature.
- **Scopes are case-sensitive and exact.** A typo in a scope name (e.g., `spend:visa_checkout` vs `spend:visa_check`) is rejected before the mandate is created. Check against the scopes reference.
- **Verify identity before spending.** Most spending scopes require a verified Sigil. If `mandate_request` fails saying identity is missing, call `kyc_start` first.
- **Mandate expiry is strict.** Once a mandate expires, it can't be approved. If the user takes too long, the request expires and they must ask the agent to try again.
- **Revoked mandates can't be undone.** Revocation is permanent. To grant the authority again, sign a new mandate.
- **Rate limits apply per agent and per network address.** If you hit `MCP-429-001-R` or `MCP-429-002-R`, wait for the `Retry-After` header and retry. Don't retry blind.
- **Offline JWT verification requires Sumvin's public keys.** Fetch them from Sumvin's published key endpoint; don't hardcode them.

## Verification checklist

Before submitting work with Sumvin:

- [ ] Mandate request includes all required scopes and parameters (e.g., `max` and `currency` for spending)
- [ ] Mandate statement is human-readable and matches what the agent will actually do
- [ ] Expiry window is reasonable (e.g., `24h`, `7d`) and user has time to approve
- [ ] Agent is not attempting to approve a mandate itself; only the user can do that
- [ ] If checking a mandate from another agent, verified it offline (JWT) and optionally online (`mandate_verify`)
- [ ] Errand description preserves the user's original phrasing (not paraphrased by agent)
- [ ] User has verified identity before requesting spending scopes
- [ ] Revocation commands target the correct mandate ID (double-check with `pint_query`)
- [ ] CLI commands use `--json` for machine parsing; human output is default
- [ ] Error codes ending in `-R` are retried; others are terminal and require input change
- [ ] No unattended agent is given `--yes` flag without human oversight

## Resources

- **Full page index:** https://docs.sumvin.com/llms.txt — comprehensive navigation for agents
- **Core concepts:** https://docs.sumvin.com/get-started/how-it-works — the four nouns and guarantees
- **MCP tools reference:** https://docs.sumvin.com/reference/mcp/tools — complete tool catalog
- **CLI reference:** https://docs.sumvin.com/reference/cli/auth — all CLI commands and flags
- **Stamped Mandates guide:** https://docs.sumvin.com/concepts/stamped-mandates — what mandates are and how they work
- **Error codes:** https://docs.sumvin.com/reference/errors — error handling and retry logic

---

> For additional documentation and navigation, see: https://docs.sumvin.com/llms.txt