Vault Scopes
Understand the difference between team-scoped and private vault secrets in WorkClaw, and when to use each scope for your credentials and API keys.
What are vault scopes?
Every secret in the WorkClaw Vault has a scope that determines who can manage it and which Claws can use it. There are two scopes: team and private.
What is team scope?
Team-scoped secrets are shared across the entire team. Any Claw on the team — whether owned by an individual member or configured at the team level — can use a team-scoped secret at runtime. Only Owners and Admins can create, edit, or delete team-scoped secrets from the Vault settings panel.
Use team scope for credentials that multiple Claws need, such as:
- A shared Slack bot token
- A company-wide CRM API key
- An SMTP credential for your organization's email server
- A shared analytics API key
What is private scope?
Private secrets belong to a single team member. Only that member can see and manage the secret, and only their personal Claws can use it at runtime. Private secrets are invisible to the rest of the team, including Owners and Admins.
Use private scope for credentials tied to an individual, such as:
- A personal GitHub access token
- An individual's calendar OAuth token
- A developer API key for a personal sandbox environment
- A private email account credential
Can I change a secret's scope?
No. Scope is set at creation time and cannot be changed. If you need to move a secret from private to team (or vice versa), create a new entry with the desired scope, update any skills or connections that reference it, and delete the old entry.
Which scope should I choose?
Ask yourself: "Should every Claw on the team be able to use this credential?" If yes, choose team. If the credential is personal or should only be used by your own Claws, choose private.
When in doubt, start with private. You can always create a team-scoped copy later if others need it. Going the other direction — discovering that a team-shared secret should have been private — is harder to unwind because Claws may already depend on it.
How do scopes interact with access control?
Scopes and roles work together. A team-scoped secret is manageable by Owners and Admins but usable by all team Claws. A private secret is manageable and usable only by its creator. See Vault Access Control for the full permissions matrix.