Available API scopes
Overview
All endpoints you can call in Workflow API require one or more specific scopes to be present in the access token, depending on the nature of the endpoint and the data it operates against. Each individual scope can be considered a form of access privilege granting specific access to specific type or group of data; in much the same way when a user account has specific privileges assigned to it, such as ability to administer a Workflow board (for instance).
During the authentication and authorization phase, when obtaining access tokens, the Applixure Authentication Server is requested to assign number of scopes for the generated access token that then limits what operations that access token is allowed to perform. These scopes are based or limited by the powers and privileges assigned to the authentication primitive was used to request that access token - in case of Applixure Workflow either user account's role assignments for Workflow Account and Board or API key's set of allowable scopes i.e. permissions.
Scopes supported by Workflow are generally divided into Account-specific and Board-specific scopes, and they have either read or read/write ("manage") permissions to Workflow objects within the scope. Account-level administration & configuration scopes - besides a scope of having all admin access to Account - do not directly have access to equivalent objects at the Board-level (i.e. inheritance); as an example, scope to read or manage API keys at the Account level does not entitle access to API keys defined at the Board-level. To manage Board-level objects an equivalent Board-specific scope has to be requested for the access token.
When requesting Board-specific scopes with Account-level API keys, such scopes are granted for all boards owned by the Account. To obtain Board-specific scope for individual board only, API key created and owned by that board must be used.
Currently supported scopes for Workflow
| SCOPE | Meaning | Covers scopes | Notes |
|---|---|---|---|
| workflow-board:read | Allows reading board contents (lanes, work items and their associated contents etc.) from Workflow board or boards | Equivalent to permissions granted for Workflow users with Viewer-role for board. | |
| workflow-workitems:update | Allows updating board's work items' contents in Workflow board or boards | workflow-board:read | Equivalent to permissions granted for Workflow users with Worker-role for board. |
| workflow-workitems:manage | Allows updating and modifying all aspects of board's work items in Workflow board or boards | workflow-workitems:update | Equivalent to permissions granted for Workflow users with Owner-role for board. |
| workflow-board-configuration-all:read | Allows reading all of board's configuration and settings for Workflow board or boards | Does not allow reading the board's contents i.e. data - explicit access using workflow-board:read or higher is required. | |
| workflow-board-configuration-rules:admin | Allows reading and administration of work item rules for Workflow board or boards | ||
| workflow-board-configuration-lanes:admin | Allows reading and administration of lanes for Workflow board or boards | ||
| workflow-board-configuration-environments:admin | Allows reading and administration of synchronized environments for Workflow board or boards | ||
| workflow-board-configuration-api:admin | Allows reading and administration of API keys for Workflow board or boards | ||
| workflow-board-configuration-users:admin | Allows reading and administration of user accounts assigned for Workflow board or boards | ||
| workflow-board-configuration-all:admin | Allows full administration of all settings and configuration of the Workflow board or boards | workflow-board-configuration-all:read, workflow-board-configuration-rules:admin, workflow-board-configuration-lanes:admin, workflow-board-configuration-environments:admin, workflow-board-configuration-api:admin, workflow-board-configuration-users:admin | |
| workflow-account-boards:read | Allows reading board contents (lanes, work items and their associated contents etc.) from all Workflow account's board or boards | ||
| workflow-account-configuration-all:read | Allows reading all of account's configuration and settings for Workflow account | ||
| workflow-account-configuration-boards:admin | Allows creating, updating settings and removal of all boards for Workflow account | ||
| workflow-account-configuration-users:admin | Allows reading and administration of Applixure Analytics user accounts added to Workflow account as Workflow users | ||
| workflow-account-configuration-api:admin | Allows reading and administration of API keys for Workflow account | ||
| workflow-account-configuration-all:admin | Allows full administration of all settings and configuration of the Workflow account | workflow-account-configuration-all:read, workflow-account-configuration-boards:admin, workflow-account-configuration-users:admin, workflow-account-configuration-api:admin | |
| workflow-account-all:admin | Allows full administration of all aspects of the Workflow account and board or boards owned by it | Covers all other scopes available | Equivalent to permissions granted for Workflow users with Account admin role for account. |
Scope covering explained
Suppose the API key has a particular scope enabled with some covered scopes listed. In that case, the caller can also request any of the listed covered scopes for the access token without explicitly enabling those covered scopes for the API key.
For example, a Board-level API key could list a workflow-workitems:update scope as its only enabled scope, but could then successfully request a workflow-board:read scope as part of the authentication call as enabled in the resulting access token.
Updated 6 months ago