Veil

Agent credential broker. Use injects the secret at the edge. Responses never include vault material. CLI, MCP, and generated SDKs are projections of this contract.

Agent

Bearer is the agent. listItems is metadata. useItem injects. Never GetSecret.

• GET
  Liveness. No secrets./health
• GET
  This contract./openapi.json
• GET
  Items this principal may see. Agent: granted. Human owner: the org. Human member: granted. Names and URIs. Never secrets./v1/items
• POST
  Call a URL as this agent. The broker injects the credential. The vault secret is never in the response./v1/use
• GET
  This agent's grant events. Decision, item, action. Never secrets. Not MCP./v1/events

Owner

Bearer is a Keto member human. Create items and grants. Secret may be sent, never returned.

• POST
  Create an item. Secret is in the request over TLS. Never in the response. Not MCP./v1/items
• POST
  One-shot 1Password .1pux or CSV onto origin. Secret in the file, never in the response. Not MCP./v1/import
• DELETE
  Remove the item and its grants. Not MCP./v1/items/{name}
• PATCH
  Replace URIs, tags, and fill username. No secret./v1/items/{name}
• POST
  Hide from Use and list. History stays./v1/items/{name}/archive
• GET
  Grants in this org. No secrets. Not MCP./v1/grants
• POST
  Grant an agent or a Kratos human Use on an item. Same grant object. Not MCP. Not a family vault./v1/grants
• GET
  Org groups. A grant to a group is the shared vault. Not MCP./v1/groups
• POST
  Create an org group. Not MCP./v1/groups
• GET
  Members of the group — agent or human edges. Not MCP./v1/groups/{name}/members
• POST
  Add an agent or human to the group. Not MCP./v1/groups/{name}/members
• DELETE
  Remove a member from the group. Not MCP./v1/groups/{name}/members/{kind}/{id}
• GET
  Agents in this org. Ids only. Never secrets. Not MCP./v1/agents
• POST
  Register an agent principal. Not a Hydra secret. Not MCP./v1/agents
• POST
  Revoke an agent. Idempotent. Kills grants, sessions, and in-flight Use. Record stays for audit./v1/agents/{name}/revoke
• GET
  Active sandbox sessions. Metadata only. Never the token. Not MCP./v1/sessions
• POST
  Mint a short-lived Use lease onto an existing agent. Token is in this response once. Sandbox gets the session file, not the agent JWT. Default 15m, max 1h. Not MCP./v1/sessions
• GET
  Approval requests filed by level-1 agents. status=open lists only unexpired asks. Not MCP./v1/requests
• GET
  Server-sent events feed of approval-request changes for the owner org. Each event is an empty tick — refetch GET /v1/requests for the authoritative rows. Not MCP./v1/requests/stream
• POST
  Approve an open request — unlocks its level-1 grant for ttl. First write wins./v1/requests/{id}/approve
• POST
  Deny an open request. First write wins; the agent's next use files a fresh ask./v1/requests/{id}/deny

Human

Bearer is a verified human ID token. Pre-membership — provision creates the membership.

• GET
  Vault health report — weak, reused, optionally breached passwords across items the human can see. Metadata only; never secrets. hibp=1 opts into k-anonymity breach lookup./v1/report
• POST
  Signup provisioning. Subject-authenticated — the bearer is a verified human ID token, not a member yet. Creates the org, seals the org master under the deployment KEK, plants the humans row, and writes the Keto owner/member tuples plus the Kratos organization_id stamp. Idempotent; safe to retry. Not MCP./v1/provision
• POST
  Private-alpha invite. Owner-authenticated — the bearer is a verified human ID token of a provisioned human. Creates the Kratos identity plus recovery link under the inviter's org and emails the setup link via the mail worker. recovery_url only appears when mail is not configured (local dev). Idempotent for re-invites. Not MCP./v1/invites
• DELETE
  Offboard a member. Owner-only — drops the Keto member tuple and the humans row; the removed member's token resolves nothing from that call on. Owners cannot be removed this way (demote first). Not MCP./v1/members/{id}
• POST
  Grant an existing member the owners tuple. Owner-only. Not MCP./v1/members/{id}/owner
• DELETE
  Strip the owners tuple from a co-owner. Owner-only. The last owner cannot be demoted — the org would have no administrator. Not MCP./v1/members/{id}/owner
• DELETE
  Leave the org: drops the member (and owner, when present) tuples plus the humans row — the token resolves nothing afterward. A sole owner is refused: promote a member or delete the org. Not MCP./v1/me
• DELETE
  Teardown. Owner-only. Deletes every Keto tuple for the org, then purges every vault row (items, grants, sessions, agents, humans, keys) in one transaction. Audit rows are kept — teardown must not erase the forensic record. Not MCP./v1/org

Billing

• GET
  Owner-facing billing state: enforced plan plus this window's use count against the free allowance. included is null when metering is off or the plan is paid. The vault's cap banner reads this. Not MCP./v1/billing
• POST
  Vortex billing webhook receiver. Auth is the Vortex-Signature header (HMAC-SHA256 over the raw body) — no org principal. Subscription and entitlement lifecycle events flip the org's plan state; unknown event types are durable no-ops. Not MCP./v1/billing/webhook
• POST
  Owner-only upgrade click: mints a fresh hosted Vortex checkout URL bound to this org. Checkout tokens are single-use and hash-pinned — never cache the URL; mint one per click. The vault's cap-banner Subscribe action. Not MCP./v1/billing/checkout

Audit

• GET
  Committed audit feed for this owner’s org — the customer SIEM pull. Keyset-paginated: poll with ?after=<next_after> until a short page lands. Events queued in the outbox join the feed on relay. Owner-only. Not MCP./v1/audit/events