Manage agent scopes, grants, and credentials

For project resources, an Agent Connection must pass three independent checks:

1. A scope permits the capability, such as reading or writing tasks.
2. A project grant permits the target project, unless the connection is explicitly all-project.
3. The authorizing user's current ACL permits the same operation.

Grant the minimum useful combination. Reading tasks does not imply changing them. Context, Notes, documents, Focus, and time use separate scopes. Destructive operations such as archive remain visibly marked and permanent deletion is not exposed through MCP.

Selected-project access is the recommended default. All-project access is appropriate only when a trusted connection must operate across the complete workspace ledger. A newly created project is not silently exposed to an unrelated selected-project connection.

For security-event triage, an owner or administrator can create a dedicated connection with only Read Security Events (security:read). It can list a bounded, safe view of security events for the workspace in its token. Project grants do not narrow this workspace-wide view. The authorizing user must still be a current workspace owner or administrator. The view excludes actor IDs, fingerprints, and full event metadata. Add project scopes only if this connection also needs project work. To use this scope through MCP, update the MCP package to a version that includes list_security_events.

Local credentials use a client ID and one-time client secret to obtain short-lived access tokens. Store them only in the agent host's approved secret configuration. Do not commit, print, paste, or pass them in shell arguments. Hosted MCP uses delegated consent, short access tokens, and rotating refresh tokens instead. Changing scopes or grants applies to later calls without rotating a local secret because ToDoddle reloads authorization on every request.

Rotate the secret when it is exposed or when custody changes. Update the host configuration and restart it, then verify a read. Disable or delete the connection to stop new tokens and calls. Also review the authorizing user's access when that person changes teams or leaves.

For a hosted connection, Disable pauses later token use and can be reversed. Revoke is permanent and invalidates consent, access grants, and refresh-token families. Authorize a new connection if access is needed after revocation.

Quarterly, review connection labels, owners, last use, scopes, and project grants. Remove capabilities that no longer support an active workflow.