Scopes and security
Understand Yodu API key scopes, role checks, secret handling, and deliberate public-platform exclusions.
Yodu applies three layers of authorization to public developer requests: the verified key, its fixed workspace and user context, and the current membership or manager role required by the operation.
Scopes
| Scope | Allows | Does not imply |
|---|---|---|
workspace:read | Read workspace identity, employees, memory, tasks, runtime visibility, and configured secret metadata | Access to another workspace or stored credential values |
workspace:write | Create and update supported work, memory, and employee configuration | Billing, member management, deletion, or secret writes |
secrets:write | Store supported provider, workspace-, employee-, tool-, and custom MCP credentials | Reading a stored value back |
The current Settings → MCP & API flow creates a key with all three scopes; it does not yet offer a scope selector. The scopes still guard individual tools and make the authorization contract explicit. Until narrower key creation is available in the UI, create a separate key per client, keep manager access narrow, approve tool use deliberately, and revoke the entire client key when it is no longer needed.
Fixed workspace boundary
The organization and user IDs are derived from the verified key. Public MCP tools do not accept an organization ID. REST operations resolve resources within the same authorized workspace.
Current roles still matter
Read and ordinary work operations require current membership. Employee provisioning, tool access, configuration, model, skill, custom MCP, and credential changes require the user's current owner or admin role. Removing a user or changing their role changes what the key can do.
Secrets are write-only
Credential values are encrypted before storage. list_secrets can return a secret's name, workspace or employee scope, provider, and update time so a client can detect existing configuration, but public responses never return the stored value. An employee-scoped secret overrides a workspace secret with the same name only for that employee. Do not pass a secret to a general-purpose tool first and ask it to copy the value into Yodu; invoke the intended write-only tool directly.
Explicitly unavailable
Public keys cannot read secret values, administer the platform, impersonate users, access billing, manage workspace membership, delete a workspace, invoke the raw runtime bootstrap, or control container lifecycle. Platform MCP exposes repair_workspace_runtime only to owners and admins and takes a safety backup first. Employee file writes are restricted to safe relative paths under skills/ and scripts/; runtime-owned root files and path traversal are rejected. Unsupported internal routes are not a compatibility surface.
Operational practices
- Create one key per client and environment.
- Store it in a secret manager and never commit it.
- Begin by invoking read-only operations, even though the current settings-created key carries all three scopes.
- Keep human approval for external, destructive, financial, or publishing actions.
- Revoke keys when a device, person, or deployment is retired.
- Never log authorization headers or tool arguments containing credentials.
- Treat a custom MCP server's own tools and authorization model as a separate security review.