Access control
Access control in Veil Keys is built around one idea: using a secret and reading a secret are different powers, and an agent should only ever have the first. Everything else — roles, grants, tokens, 2FA — exists to keep that separation crisp and enforceable.
Organizations and roles
Every account belongs to an organization (a “personal” account is just an organization of one). An org has four roles:
| Role | Scope |
|---|---|
| owner | Full control of the org and all its workspaces, including billing and 2FA enforcement |
| admin | Full access to the org’s workspaces; manage members and grants |
| member | Only what an explicit per-workspace grant gives them |
| viewer | Only what an explicit per-workspace grant gives them |
Owners and admins have full access to the org’s workspaces by virtue of their role. Members and viewers start with nothing — they see and do only what a workspace grant explicitly allows. There is no ambient access.
The five per-workspace permissions
A grant assigns any combination of five permissions, scoped to a single workspace:
| Permission | Means |
|---|---|
| read | See that a credential exists (its name and host) — never its value |
| write | Add, edit, and fill credentials |
| use | Let an agent or broker use a credential — the value is injected, never shown |
| reveal | See a credential’s plaintext, or repoint where a filled secret is sent |
| manage | Grant and revoke others’ access in the workspace |
Reveal-equivalent guard
Holding write is not a back door to reveal. A user with write but not reveal cannot change
where a filled secret is sent — its host, OAuth token URL, AWS target, or injection header. Quietly
repointing a secret to a destination you control is exfiltration, so it is blocked at the reveal
level. See Domain binding.
Agent tokens narrow access further
Permissions are the ceiling; tokens go below it. An agent, CI, or SSH token can be scoped to specific tools, methods, and a single workspace — and a token can never exceed the permissions of the person who created it. A token narrows your access; it never widens it. If your grant later shrinks, so does the token’s reach.
See Token types for the full breakdown.
Two-factor authentication (TOTP)
Veil Keys supports TOTP two-factor authentication:
- Optional for individuals — any user can enroll an authenticator app.
- Org-enforceable by owners and admins — an org can require 2FA. When enforced, agents and CI for that org are refused until the user enrolls, so a non-human client can’t quietly bypass the policy that protects its creator’s account.
Auth hardening
The boundary around accounts is hardened with standard, named measures:
| Measure | Protects against |
|---|---|
| argon2id password hashing | Offline cracking of a stolen credential store |
| JWT sessions + instant kill-switch | Lingering access after compromise — sessions can be revoked instantly |
| Per-session revocation | Killing one device without logging out the rest |
| TOTP replay protection | Reuse of an intercepted one-time code |
| One-time recovery codes | Lockout when an authenticator is lost |
| Password reset revokes all sessions | A reset on a compromised account also evicts the attacker |
| Reveal rate-limiting (per user) | Bulk extraction of plaintext through repeated reveals |
What this model does and doesn’t protect
- It protects against compromised agents. A
use-only agent, fully subverted, still can’t read a secret. - It protects against over-broad tokens. Tokens can only ever do less than their creator.
- It does not make a stolen
reveal-holding session harmless. Someone who steals an owner or admin session can reveal — which is why 2FA is enforceable, reveals are rate-limited, and a password reset kills every session. Grantrevealsparingly.