API key scopes

Use this page as a quick reference for API key scopes, what each one allows, and how empty scopes behave.

For concepts, read API keys and programmatic access. For setup, read Manage API keys and service accounts.

Empty scopes mean full access

When a key's scope list is empty, it has full permissions for its identity:

• A personal key can do anything your user account can do in workspaces and projects you can access.
• A service account key can do anything allowed by the project roles assigned to that service account.

Empty scopes exist for backward compatibility and for clients that need the full MCP tool surface. Prefer explicit scopes when you know the integration's needs.

Scope catalog

Scope	Allows
issues:read	Read issues and issue-related data: list and get issues, search, count issues, read comments and attachments metadata, list labels, list cycles and epics needed for issue context, and use read-only MCP tools such as list_issues, get_issue, and search.
issues:write	Create, update, transition, and delete issues; post comments; manage labels and issue links; set cycles and epics on issues (via update_issue); and use write MCP tools such as create_issue, update_issue, transition_issue, and bulk_update_issues. Requires normal project write access for the key's identity.
webhooks:manage	Create, update, and delete workspace webhook subscriptions through the REST API. Does not by itself grant issue read or write.
projects:read	List and read projects and project metadata in workspaces you can access, including MCP tools such as list_projects and get_project.
workspace:read	List workspaces and read workspace-level metadata, including MCP tools such as list_workspaces.

Scopes are an allowlist. A key with only issues:read cannot create issues even if the underlying user or service account has write access in the UI.

Common combinations

Integration need	Suggested scopes
Read-only dashboard or report script	issues:read, projects:read, workspace:read
CI job that comments on or updates issues	issues:read, issues:write, projects:read
Webhook provisioning automation	webhooks:manage, workspace:read
Full MCP assistant (personal use)	Empty scopes (full access) or explicit read/write scopes covering the tools you use

REST routes and scopes

When a key has non-empty scopes, Tixio checks scopes on REST calls in addition to normal membership checks:

• GET under /v1/workspaces/… generally requires workspace:read, projects:read, or issues:read depending on the resource.
• Issue mutations under /v1/workspaces/…/issues require issues:write.
• Webhook subscription changes require webhooks:manage.

Routes not matched by a scope rule still require at least one granted scope and normal RBAC. JWT browser sessions bypass scope checks entirely.

MCP tools and scopes

MCP tools map to scopes when the key is scoped. Examples:

MCP tool	Required scope
list_workspaces	workspace:read
list_projects, get_project	projects:read
list_issues, get_issue, search, count_issues	issues:read
create_issue, update_issue, transition_issue, bulk_update_issues	issues:write

Tools not listed in the mapping require issues:write when the key is scoped. Unlisted tools are unavailable to narrowly scoped read-only keys.

Invalid scopes

Key creation and rotation reject unknown scope strings. Use only the scopes in the catalog above.

Learn more

For token format, rotation grace, and audit events, read API keys and programmatic access.