Scopes and permissions

Every /api/v2 request passes two separate checks, and every operation page states what each one needs.

The token is only ever a ceiling. Permissions are read again on every request, so taking a permission away from a role narrows existing tokens at once, without touching them.

The two failures have different fixes. A scope failure needs a different token; a permission failure needs a role change. The full order of checks, from the organisation's switch to the record's state, is in Authentication.

How a scope is built

An ability is api:{class} or api:{class}:{prefix}.

• class is read, write or destroy. On the API tokens page they are called Read, Write and Delete.
• prefix is the resource, spelled as in the permission names, such as projects, project_management or work_types. API tokens maps each prefix to the name the token form shows.

Leave out the prefix and the ability covers every resource of its class: api:write satisfies an operation that asks for api:write:projects.

An app that signs people in with OAuth asks for these same strings as OAuth scopes, except the destroy class, which OAuth never offers.

The class ladder

Each class includes the ones below it: write includes read, and destroy includes both.

Every DELETE needs the destroy class, whether it deletes softly or for good. force=true is accepted on DELETE/projects/{project} alone. There it deletes the project for good, and it checks the same projects::delete permission as a soft delete. See Deleting and restoring.

Some operations list more than one scope. Any one of them is enough. They are the drive operations, where one endpoint serves items owned by a project, a customer, the organisation or a user, plus the comment and upload operations that work items and drive items share.

Token scopes

A token can carry every class with every resource, plus the three unnarrowed abilities api:read, api:write and api:destroy. 82 of them are named by at least one operation, and the table below lists those, with what each covers. api:write and api:destroy are not in it because no operation names them, but api:write satisfies every read and write, and api:destroy every read, write and delete.

OAuth apps may ask for the read and write abilities only.

Permissions

67 permissions gate /api/v2. They are the same permissions plnnrly checks in the app, so an integration can do exactly what the user behind the token can do there, and no more.

A permission is {prefix}::{action}, such as projects::update. The prefix is usually the one a narrowed scope names, so api:write:projects and projects::update guard the same thing from two sides. Time is the exception: reading worklogs needs the scope api:read:times and the permission hours::read.

The drive operations name project_drive::access or project_drive::create. For items owned by a customer, the organisation or a user, plnnrly checks the matching customer_drive, organization_drive or user_drive permission instead.

Operations that need no permission

A few operations need a valid token with the right scope and no permission at all. Their pages say so.

• Discovery and GET/me.
• Reading and cancelling an upload ticket.
• Creating, changing and deleting your own worklogs, timers and check-ins, and reading your own furlough mutations. The record's own rules are the gate here, not a permission.

Other people's rows need a permission after all:

• worklogs: times::update_others or times::delete_others, and times::update_others to log time for someone else with on_behalf_of_user_id
• furlough mutations: furlough::view_all or furlough::manage

Permissions that change what a call does

Some permissions do not decide whether a call runs, but what it may do.

Fields with a permission of their own. Sending one of these fields without its permission answers 403 insufficient-permission naming the field, except is_overtime, which is dropped instead.

A dropped field does not fail the call, so check meta.warnings after every write.

Permissions that widen which rows you reach. Without them you see and change only your own rows:

• times::update_others and times::delete_others: other people's worklogs
• kanban::manage_for_others: other people's kanban tasks
• events::manage_for_others: other people's agenda events
• furlough::view_all and furlough::manage: other people's furlough mutations

Permissions a record's rules ask for. A few writes check a further permission on the record you write to, and answer 403 forbidden-by-policy without it:

• projects::notes: adding a note to a project
• times::write_on_others_tasks: logging time on a task that belongs to someone else

Each operation page names the permissions that apply to it.

What your organisation exposes

Call GET/ with any API token. It answers one entry per resource your organisation has, each with its permission_prefix, so you can match it with the tables above.

Discovery only leaves out resources of features your organisation does not have. It does not check your token or your role, so a listed resource can still answer 403 for you.

Related

• API tokens: creating a token with the right scopes.
• Authentication: the full order of checks.
• Errors and retries: every problem type and its fix.