Safety and permissions

Agents in Whagons are actors within the existing tenant authorization model, not a bypass around it.

Shared principles

These principles apply to both delegated external agents and the built-in assistant:

1. Act as a known user. Every operation must resolve to an authenticated or approving user.
2. Stay inside one tenant. A credential cannot be used to cross tenant boundaries.
3. Honor current permissions. Role, team, workspace, task, field, and lifecycle controls still apply.
4. Minimize scope. Request only the read or task-write scope the workflow requires.
5. Confirm consequential changes. Destructive or high-impact actions need clear user intent.
6. Verify outcomes. Never claim a write succeeded without a confirmed response.
7. Protect secrets. Credentials must not be placed in chat, logs, screenshots, issue trackers, or documentation.

External agent safeguards

• The user-claimed flow requires a matching email, six-digit code, sign-in, and tenant selection.
• Anonymous pre-claim access is disabled.
• Access tokens expire after the lifetime returned by the token service.
• Token activity is tied to the agent registration and approving user for auditability.
• Revoked, expired, wrong-tenant, or under-scoped credentials fail authentication.

Built-in assistant safeguards

• Read operations use only data visible to the signed-in user.
• Curated write actions validate their payloads and product rules.
• Bulk operations should use preview-and-apply flows.
• Destructive actions require explicit intent and confirm: true where the action supports it.
• Role changes, ownership transfer, user removal, key creation, and similar operations receive additional caution.
• Raw backend calls are fallback-only and should never be used to bypass a supported curated action.

API-key safeguards

Settings-issued keys are long-lived compared with agent tokens. Use a separate key for each integration and environment, choose an expiration when possible, copy it once into a secret manager, and revoke it during offboarding or rotation.

The Settings UI currently issues both external scopes by default. Restrict the key creator's roles, teams, and workspaces to keep the effective access appropriate.

Incident response

If a key or agent token may be exposed:

1. Disable or revoke the credential immediately.
2. Review the affected integration or agent logs without copying the secret.
3. Review Whagons task logs and agent audit activity for unexpected changes.
4. Rotate any related integration secrets.
5. Correct the user's permissions or team membership if effective access was too broad.
6. Create a fresh credential only after the cause is understood.

For the authorization layers behind these rules, see Permissions and visibility.