Governance and security

OAuth apps and scopes

Let other applications act on UserTasks with OAuth 2.0: discovery, PKCE, client credentials, consent, refresh and revocation.

UserTasks is an OAuth 2.0 authorization server for its own API and MCP server.

Endpoint	Purpose
`/.well-known/oauth-authorization-server`	Authorization server metadata
`/.well-known/oauth-protected-resource`	Protected resource metadata (for MCP clients)
`/api/oauth/register`	Dynamic client registration
`/api/oauth/authorize` → `/oauth/consent`	Authorization code flow with PKCE (S256) and user consent
`/api/oauth/token`	`authorization_code`, `refresh_token` and `client_credentials` grants
`/api/oauth/revoke`	Token revocation

Register apps in Settings → OAuth Apps (public or confidential, redirect URIs, grant types, allowed scopes) or let MCP clients register themselves dynamically.

Security properties

Authorization codes are single use; replaying one revokes the tokens issued with it (security.oauth.code_replay).
Refresh tokens rotate on every use; presenting an old one revokes the family (security.oauth.refresh_reuse).
Consent, token issue and revocation are audited security events.
A token's permissions are the intersection of its scopes and the user's current permissions, re-checked on every request.

Scopes

Scopes are coarse grants that expand to permissions. Generated from lib/oauth/scopes.ts:

Scope	Grants	Expands to
`tasks:read`	Read tasks and their status	`tasks.view_own` `tasks.view_all`
`tasks:write`	Create, assign, complete, and manage tasks	`tasks.view_own` `tasks.view_all` `tasks.create` `tasks.assign` `tasks.complete` `tasks.redirect` `tasks.escalate` `tasks.delete` `tasks.manage_queue`
`workflows:read`	Read workflow definitions and run history	`workflows.view` `workflows.view_runs`
`workflows:write`	Create, edit, activate, and start workflows	`workflows.view` `workflows.view_runs` `workflows.create` `workflows.edit` `workflows.activate` `workflows.delete` `workflows.manage_runs`
`data:read`	Read data tables and rows	`data.view`
`data:write`	Create and modify data tables and rows	`data.view` `data.create` `data.edit_schema` `data.manage_rows` `data.delete`
`reports:read`	Read reports	`reports.view`
`reports:write`	Create, edit, share, and delete reports	`reports.view` `reports.create` `reports.edit_own` `reports.share` `reports.delete`
`agents:read`	Read AI agent definitions	`agents.view`
`agents:write`	Create, edit, test, and delete AI agents	`agents.view` `agents.create` `agents.edit` `agents.test` `agents.delete`
`integrations:read`	Read integrations, connectors, and references	`integrations.view`
`integrations:write`	Create, edit, test, and delete integrations, connectors, and references	`integrations.view` `integrations.create` `integrations.edit` `integrations.test` `integrations.delete` `integrations.manage_references`
`extensibility:read`	Read custom workflow activities	`extensibility.view`
`extensibility:write`	Create, edit, and delete custom workflow activities	`extensibility.view` `extensibility.create` `extensibility.edit` `extensibility.delete`
`settings:read`	Read workspace settings	`settings.view`
`settings:write`	Edit workspace settings and webhooks	`settings.view` `settings.edit` `settings.manage_webhooks`
`team:read`	Read workspace members and teams	`team.view_members`
`team:write`	Invite and remove members, and change their roles	`team.view_members` `team.invite` `team.remove` `team.change_roles`
`sync:read`	Read GitHub sync status and history	`sync.view`
`sync:write`	Manage GitHub sync and run deployments	`sync.view` `sync.manage` `sync.deploy`
`packages:read`	Read packages, their versions and the installed package library	`packages.view`
`packages:write`	Author, build, install, upgrade and uninstall packages	`packages.view` `packages.manage` `packages.install`
`events:read`	Read and stream workflow, integration, agent and task events (audit and security events also need settings:read)	`observability.view`
`workflows:run`	Start workflows and read run history	`workflows.view` `workflows.view_runs` `workflows.create` `workflows.edit` `workflows.activate` `workflows.delete` `workflows.manage_runs`
`config:read`	Export workspace configuration (workflows, rules, tables, integrations, agents, reports) and read packages	`workflows.view` `workflows.view_runs` `data.view` `integrations.view` `extensibility.view` `agents.view` `reports.view` `packages.view` `settings.view`
`config:write`	Import and update workspace configuration (workflows, rules, tables, integrations, agents, reports), and author and install packages	`workflows.view` `workflows.view_runs` `workflows.create` `workflows.edit` `workflows.activate` `workflows.delete` `workflows.manage_runs` `data.view` `data.create` `data.edit_schema` `data.manage_rows` `data.delete` `integrations.view` `integrations.create` `integrations.edit` `integrations.test` `integrations.delete` `integrations.manage_references` `extensibility.view` `extensibility.create` `extensibility.edit` `extensibility.delete` `agents.view` `agents.create` `agents.edit` `agents.test` `agents.delete` `reports.view` `reports.create` `reports.edit_own` `reports.share` `reports.delete` `packages.view` `packages.manage` `packages.install` `settings.view` `settings.edit`
`keys:write` (first-party CLI only)	Create and revoke API keys on your behalf	`settings.view` `settings.manage_api_keys`
`mcp`	Connect via MCP (Model Context Protocol)	access to /api/mcp (tools still need their permissions)
`admin`	Full administrative access to the workspace API	every permission

The UserTasks CLI is a first-party client: usertasks login requests every scope except keys:write unless you pass --scopes.