Security namespace and permission reference for Azure DevOps

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

This article describes the valid security namespaces, lists the associated permissions, and provides links to more information. Security namespaces store access control lists (ACLs) on tokens, determining the level of access various entities have to perform specific actions on specific resources. These entities include:

  • Azure DevOps users
  • Azure DevOps organization owners
  • Members of Azure DevOps security groups
  • Azure DevOps service accounts
  • Azure DevOps service principals

Each family of resources, such as work items or Git repositories, is secured through a unique namespace. Each security namespace contains zero or more ACLs. An ACL includes a token, an inherit flag, and a set of zero or more access control entries (ACEs). Each ACE consists of an identity descriptor, an allowed permissions bitmask, and a denied permissions bitmask. Tokens are arbitrary strings representing resources in Azure DevOps.

Note

Namespaces and tokens are valid for all versions of Azure DevOps. Those listed here are valid for Azure DevOps 2019 and later versions. Namespaces are subject to change over time. To get the latest list of namespaces, exercise one of the command line tools or REST API. Some namespaces have been deprecated as listed in the Deprecated and read-only namespaces section later in this article. For more information, see Security namespaces query

Permission management tools

The recommended method for managing permissions is through the web portal. However, to set permissions that are unavailable through the portal or to manage granular permissions, use command line tools or the REST API:

For all Azure DevOps instances, you can also use the Security REST API.

Security namespaces and their IDs

Many security namespaces correspond to permissions you set through a Security or Permissions web portal page. Other namespaces or specific permissions aren't visible through the web portal and grant access by default to members of security groups or Azure DevOps service principals. These namespaces are grouped into the following categories based on how they're managed through the web portal:

  • Object-level
  • Project-level
  • Organization or collection-level
  • Server-level (on-premises only)
  • Role-based
  • Internal only

Hierarchy and tokens

A security namespace can be either hierarchical or flat. In a hierarchical namespace, tokens exist in a hierarchy where effective permissions are inherited from parent tokens to child tokens. In contrast, tokens in a flat namespace have no parent-child relationship.

Tokens in a hierarchical namespace can have either fixed-length or variable-length path parts. If the tokens have variable-length path parts, a separator character is used to distinguish where one path part ends and another begins.

Security tokens are case-insensitive. Examples of tokens for different namespaces are provided in the following sections.

Object-level namespaces and permissions

The following table describes the namespaces that manage object-level permissions. Most of these permissions are managed through the web portal page for each object. Permissions are set at the project level and inherited at the object level unless explicitly changed.


Namespace

Permissions

Description


AnalyticsViews

Read
Edit
Delete
Execute
ManagePermissions

Manages Analytics views permissions at the project-level and object-level to read, edit, delete, and generate reports. You can manage these permissions for each analytics view from the user interface.

Token format for project level permissions: $/Shared/PROJECT_ID
Example: $/Shared/xxxxxxxx-aaaa-1111-bbbb-11111

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Build

ViewBuilds
EditBuildQuality
RetainIndefinitely
DeleteBuilds
ManageBuildQualities
DestroyBuilds
UpdateBuildInformation
QueueBuilds
ManageBuildQueue
StopBuilds
ViewBuildDefinition
EditBuildDefinition
DeleteBuildDefinition
OverrideBuildCheckInValidation
AdministerBuildPermissions

Manages build permissions at the project-level and object-level.

Token format for project-level build permissions: PROJECT_ID
If you need to update permissions for a particular build definition ID, for example, 12, security token for that build definition looks like the following example:
Token format for project-level, specific build permissions: PROJECT_ID/12
Example: xxxxxxxx-aaaa-1111-bbbb-11111/12

ID: xxxxxxxx-aaaa-1111-bbbb-11111


CSS

GENERIC_READ
GENERIC_WRITE
CREATE_CHILDREN
DELETE
WORK_ITEM_READ
WORK_ITEM_WRITE
MANAGE_TEST_PLANS
MANAGE_TEST_SUITES

Manages area path object-level permissions to create, edit, and delete child nodes and set permissions to view or edit work items in a node. For more information, see Set permissions and access for work tracking, Create child nodes, modify work items under an area path.
Token format example: POST https://dev.azure.com/{organization}/_apis/securitynamespaces/{namespaceId}/permissions?api-version=6.0 { "token": "vstfs:///Classification/Node/{area_node_id}", "permissions": { "allow": 1, "deny": 0 } }
ID: xxxxxxxx-aaaa-1111-bbbb-11111


DashboardsPrivileges

Read
Create
Edit
Delete
ManagePermissions
MaterializeDashboards

Manages dashboard object-level permissions to edit and delete dashboards and manage permissions for a project dashboard. You can manage these permissions through the dashboards user interface.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Git Repositories

Administer
GenericRead
GenericContribute
ForcePush
CreateBranch
CreateTag
ManageNote
PolicyExempt
CreateRepository
DeleteRepository
RenameRepository
EditPolicies
RemoveOthersLocks
ManagePermissions
PullRequestContribute
PullRequestBypassPolicy

Manages Git repository permissions at the project-level and object-level. You can manage these permissions through the Project settings, Repositories administrative interface.

The Administer permission was divided into several more granular permissions in 2017, and shouldn't be used.
Token format for project-level permissions: repoV2/PROJECT_ID
You need to append RepositoryID to update repository-level permissions.

Token format for repository-specific permissions: repoV2/PROJECT_ID/REPO_ID

Token format for branch-level permissions is described in Git repo tokens for the security service.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Iteration

GENERIC_READ
GENERIC_WRITE
CREATE_CHILDREN
DELETE

Manages iteration path object-level permissions to create, edit, and delete child nodes and view child node permissions. To manage through the web portal, see Set permissions and access for work tracking, Create child nodes.
Token format: 'vstfs:///Classification/Node/Iteration_Identifier/'
Suppose, you have the following iterations configured for your team.
– ProjectIteration1
  TeamIteration1
     – TeamIteration1ChildIteration1
     – TeamIteration1ChildIteration2
     – TeamIteration1ChildIteration3
  TeamIteration2
     – TeamIteration2ChildIteration1
     – TeamIteration2ChildIteration2

To update permissions for ProjectIteration1\TeamIteration1\TeamIteration1ChildIteration1, the security token looks like the following example:
vstfs:///Classification/Node/ProjectIteration1_Identifier:vstfs:///Classification/Node/TeamIteration1_Identifier:vstfs:///Classification/Node/TeamIteration1ChildIteration1_Identifier

ID: xxxxxxxx-aaaa-1111-bbbb-11111


MetaTask

Administer
Edit
Delete

Manages task group permissions to edit and delete task groups, and administer task group permissions. To manage through the web portal, see Pipeline permissions and security roles, Task group permissions.

Token format for project-level permissions: PROJECT_ID
Token format for metaTask-level permissions: PROJECT_ID/METATASK_ID

If MetaTask has parentTaskId, then the Security token looks like the following example:
Token Format: PROJECT_ID/PARENT_TASK_ID/METATASK_ID

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Plan

View
Edit
Delete
Manage

Manages permissions for Delivery Plans to view, edit, delete, and manage delivery plans. You can manage these permissions through the web portal for each plan.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


ReleaseManagement

ViewReleaseDefinition
EditReleaseDefinition
DeleteReleaseDefinition
ManageReleaseApprovers
ManageReleases
ViewReleases
CreateReleases
EditReleaseEnvironment
DeleteReleaseEnvironment
AdministerReleasePermissions
DeleteReleases
ManageDeployments
ManageReleaseSettings
ManageTaskHubExtension

Manages release definition permissions at the project and object-level.

Token format for project-level permissions: PROJECT_ID
Example: xxxxxxxx-aaaa-1111-bbbb-11111
If you need to update permissions for a particular release definition ID, for example, 12, security token for that release definition looks like the following example:

Token format for specific release definition permissions: PROJECT_ID/12
Example: xxxxxxxx-aaaa-1111-bbbb-11111/12
If the release definition ID lives in a folder, then the security tokens look as follows:
Token format: PROJECT_ID/{folderName}/12
For stages, tokens look like: PROJECT_ID/{folderName}/{DefinitionId}/Environment/{EnvironmentId}.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


WorkItemQueryFolders

Read
Contribute
Delete
ManagePermissions
FullControl
RecordQueryExecutionInfo

Manages permissions for work item queries and query folders. To manage these permissions through the web portal, see Set permissions on queries or query folders. Token format example: POST https://dev.azure.com/{organization}/_apis/securitynamespaces/{namespaceId}/permissions?api-version=6.0 { "token": "/{project_id}/{shared_queries_id}", "permissions": { "allow": 1, "deny": 0 } }.
ID: xxxxxxxx-aaaa-1111-bbbb-11111


Project-level namespaces and permissions

The following table describes the namespaces that manage project-level permissions. Most of the listed permissions are managed through the web portal admin context. Project Administrators are granted all project-level permissions, while other project-level groups have specific permission assignments.


Namespace

Permissions

Description


Project

GENERIC_READ
GENERIC_WRITE
DELETE
PUBLISH_TEST_RESULTS
ADMINISTER_BUILD
START_BUILD
EDIT_BUILD_STATUS
UPDATE_BUILD
DELETE_TEST_RESULTS
VIEW_TEST_RESULTS
MANAGE_TEST_ENVIRONMENTS
MANAGE_TEST_CONFIGURATIONS
WORK_ITEM_DELETE
WORK_ITEM_MOVE
WORK_ITEM_PERMANENTLY_DELETE
RENAME
MANAGE_PROPERTIES
MANAGE_SYSTEM_PROPERTIES
BYPASS_PROPERTY_CACHE
BYPASS_RULES
SUPPRESS_NOTIFICATIONS
UPDATE_VISIBILITY
CHANGE_PROCESS
AGILETOOLS_BACKLOG
AGILETOOLS_PLANS

Manages Project-level permissions.
The AGILETOOLS_BACKLOG permission manages access to Azure Boards backlogs. This setting is an internal permission setting and shouldn't be changed.

Root token format: $PROJECT
Token to secure permissions for each project in your organization.
$PROJECT:vstfs:///Classification/TeamProject/PROJECT_ID.

Assume you have a project named Test Project 1.
You can get the project ID for this project by using the az devops project show command.
az devops project show --project "Test Project 1"
The command returns a project-id, for example, xxxxxxxx-aaaa-1111-bbbb-11111.
Therefore, the token to secure project-related permissions for Test Project 1 is:
'$PROJECT:vstfs:///Classification/TeamProject/xxxxxxxx-aaaa-1111-bbbb-11111'


**ID:** `xxxxxxxx-aaaa-1111-bbbb-11111`

Tagging

Enumerate
Create
Update
Delete

Manages permissions to create, delete, enumerate, and use work item tags. You can manage the Create tag definition permission through the permissions administrative interface.

Token format for project-level permissions: /PROJECT_ID
Example: /xxxxxxxx-aaaa-1111-bbbb-11111

ID: xxxxxxxx-aaaa-1111-bbbb-11111


VersionControlItems

Read
PendChange
Checkin
Label
Lock
ReviseOther
UnlockOther
UndoOther
LabelOther
AdminProjectRights
CheckinOther
Merge
ManageBranch

Manages permissions for a Team Foundation Version Control (TFVC) repository. There's only one TFVC repository for a project. You can manage these permissions through the repositories administrative interface.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Organization-level namespaces and permissions

The following table describes the namespaces that manage organization-level permissions. Most of the listed permissions are managed through the web portal Organization settings context. The Organization owner and members of the Project Collection Administrators group are granted most of these permissions. For more information, see Change project collection-level permissions.

Collection-level namespaces and permissions

The following table describes the namespaces that manage organization-level permissions. Most of the listed permissions are managed through the web portal Collection settings context. Members of the Project Collection Administrators group are granted most of these permissions. For more information, see Change project collection-level permissions.


Namespace

Permissions

Description


AuditLog

Read
Write
Manage_Streams
Delete_Streams

Manages auditing permissions to read or write to the audit log and manage or delete audit streams.

Token format: /AllPermissions
ID: xxxxxxxx-aaaa-1111-bbbb-11111


BuildAdministration

ViewBuildResources
ManageBuildResources
UseBuildResources
AdministerBuildResourcePermissions
ManagePipelinePolicies


Collection

GENERIC_READ
GENERIC_WRITE
CREATE_PROJECTS
TRIGGER_EVENT
MANAGE_TEMPLATE
DIAGNOSTIC_TRACE
SYNCHRONIZE_READ
MANAGE_TEST_CONTROLLERS
DELETE_FIELD
MANAGE_ENTERPRISE_POLICIES


Process

Edit
Delete
Create
AdministerProcessPermissions
ReadProcessPermissions


Workspaces

Read
Use
Checkin
Administer

Manages permissions for administering shelved changes, workspaces, and the ability to create a workspace at the organization or collection level. The Workspaces namespace applies to the TFVC repository.

Root token format: /
Token format for a specific workspace: /{workspace_name};{owner_id}

ID: xxxxxxxx-aaaa-1111-bbbb-11111


VersionControlPrivileges

CreateWorkspace
AdminWorkspaces
AdminShelvesets
AdminConnections
AdminConfiguration

Manages permissions for Team Foundation Version Control (TFVC) repository.

The AdminConfiguration permission grants users the ability to edit server-level permissions for users and groups. The AdminConnections permission grants users the ability to read the contents of a file or folder of an on-premises, server-level repository.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Server-level namespaces and permissions

The following table describes those security namespaces and permissions defined for on-premises instances. You can manage these permissions, which are granted to members of the Team Foundation Administrators group, through the Azure DevOps Server administration console. For descriptions of these permissions, see Permissions and groups, Server-level permissions.


Namespace

Permissions

Description


CollectionManagement

CreateCollection
DeleteCollection

Manages permissions set at the server-level to create and delete project collections.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Server

GenericRead
GenericWrite
Impersonate
TriggerEvent

Manages permissions set at the server-level. Includes permissions to edit instance-level information, make requests on behalf of others, and trigger events.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Warehouse

Administer

Grants permission to process or change settings for the data warehouse or SQL Server Analysis cube by using the Warehouse Control Web Service.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Role-based namespaces and permissions

The following table describes the security namespaces and permissions used to manage role-based security. You can manage role assignments through the web portal for pipeline resources as described Pipeline permissions and security roles.


Namespace

Permissions

Description


DistributedTask

View
Manage
Listen
AdministerPermissions
Use
Create

Manages permissions to access agent pool resources. By default, the following roles and permissions are assigned at the project level and inherited for each agent pool that is created:

  • Reader role (View permissions only) to all members of the Project Valid Users group
  • Administrator role (all permissions) to members of the Build Administrators, Project Administrators, and Release Administrators groups.
  • User role (View, Use, and Create permissions) to all members of the Contributor group
  • Creator role (View, Use, and Create permissions) to all members of the Contributor group

    ID: xxxxxxxx-aaaa-1111-bbbb-11111

Environment

View
Manage
ManageHistory
Administer
Use
Create

Manages permissions to create and manage Environments. By default, the following permissions are assigned:

  • Reader role (View permissions only) to all members of the Project Valid Users group
  • Creator role (View, Use, and Create permissions) to all members of the Contributor group
  • Creator role (View, Use, and Create permissions) to all members of the Project Administrators group
  • Administrator role (all permissions) to the user who created a specific Environment.

    ID: xxxxxxxx-aaaa-1111-bbbb-11111

ExtensionManagement

ViewExtensions
ManageExtensions
ManageSecurity

The Manager role is the only role used to manage the security of Marketplace extensions. Members of the Manager role can install extensions and respond to requests for extensions to be installed. The other permissions are assigned automatically to members of default security groups and service principals. To add users to the Manager role, see Manage extension permissions.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Library

View
Administer
Create
ViewSecrets
Use
Owner

Manages permissions to create and manage library items, which include secure files and variable groups. Role memberships for individual items are automatically inherited from the Library. By default, the following permissions are assigned:

  • Reader role (View permissions only) to all members of the Project Valid Users group and the Project Collection Build Service account
  • Creator role (View, Use, and Create permissions) to all members of the Contributors group
  • Creator role (View, Use, Create, and Owner permissions) to the member who created the library item
  • Administrator role (all permissions) to members of the Build Administrators, Project Administrators, and Release Administrators groups.
    For more information, see Library asset security roles.

    ID: xxxxxxxx-aaaa-1111-bbbb-11111

ServiceEndpoints

Use
Administer
Create
ViewAuthorization
ViewEndpoint

Manages permissions to create and manage service connections. Role memberships for individual items are automatically inherited from the project-level roles. By default, the following roles are assigned:

  • Reader role (View permissions only) to all members of the Project Valid Users group and the Project Collection Build Service account
  • Creator role (View, Use, and Create permissions) to members of the Endpoint Creators service security group.
  • Administrator role (all permissions) to members of the Endpoint Administrators service security group.
    Roles are assigned through Service connection security roles.

    ID: xxxxxxxx-aaaa-1111-bbbb-11111

Internal namespaces and permissions

The following table describes the security namespaces and permissions that aren't surfaced through the web portal. They're primarily used to grant access to members of default security groups or to internal resources. We strongly recommend that you don't alter these permission settings in any way.


Namespace

Permissions

Description


AccountAdminSecurity

Read
Create
Modify

Manages permissions to read or modify the organization account owner. These permissions are assigned to the organization owner and members of the Project Collection Administrator group.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Analytics

Read
Administer
Stage
ExecuteUnrestrictedQuery
ReadEuii

Manages permissions to read, administer permissions, and execute queries against the Analytics service.

Token format for project-level permissions: $/PROJECT_ID
Example: $/xxxxxxxx-aaaa-1111-bbbb-11111

ID: xxxxxxxx-aaaa-1111-bbbb-11111


BlobStoreBlobPrivileges

Read
Delete
Create
SecurityAdmin

Sets permissions to read, delete, create, and manage the security of the data store. These permissions are assigned to several Azure DevOps service principals.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Boards

View
Create
ChangeMetadata
MoveCard
Delete
Manage

Manages permissions and access to boards.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


BoardsExternalIntegration

Read
Write

Manages read/write permissions of external integrations with Azure Boards.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Chat

ReadChatRoomMetadata
UpdateChatRoomMetadata
CreateChatRoom
CloseChatRoom
DeleteChatRoom
AddRemoveChatRoomMember
ReadChatRoomMessage
WriteChatRoomMessage
UpdateChatRoomMessage
DeleteChatRoomMessage
ReadChatRoomTranscript
ManageChatPermissions

Manages permissions for chat services integrated with Azure DevOps, such as Slack and Microsoft Teams. For more information, see Azure Boards with Slack, Azure Boards with Microsoft Teams, Azure Pipelines with Slack, Azure Pipelines with Microsoft Teams, Azure Repos with Slack, and Azure Repos with Microsoft Teams.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Discussion Threads

Administer
GenericRead
GenericContribute
Moderate

Manages permissions to view, manage, moderate, and contribute to code review discussions setup for Azure Pipelines.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


EventPublish

Read
Write

Grants read and write access for notification handler.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


EventSubscriber

GENERIC_READ
GENERIC_WRITE

Grants read and write access for notification subscribers.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


EventSubscription

GENERIC_READ
GENERIC_WRITE
UNSUBSCRIBE
CREATE_SOAP_SUBSCRIPTION

Manages member permissions to view, edit, and unsubscribe from notifications or create a SOAP subscription.

ID: xxxxxxxx-aaaa-1111-bbbb-11111

Identity

Read
Write
Delete
ManageMembership
CreateScope
RestoreScope

Manages permissions to read, write, and delete user account identity information; manage group membership and create and restore identity scopes. The ManageMembership permission is automatically granted to members of the Project Administrators and Project Collection Administrators groups.
Token format for project-level permissions: PROJECT_ID
Example: xxxxxxxx-aaaa-1111-bbbb-11111
To modify group level permissions for Group Origin ID [xxxxxxxx-aaaa-1111-bbbb-11111]:
Token: xxxxxxxx-aaaa-1111-bbbb-11111\xxxxxxxx-aaaa-1111-bbbb-11111

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Licensing

Read
Create
Modify
Delete
Assign
Revoke

Manages the ability to view, add, modify, and remove license levels. These permissions are automatically granted to members of the Project Collection Administrators groups.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


PermissionLevel

Read
Create
Update
Delete

Manages the ability to create and download permission reports.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


OrganizationLevelData

Project-Scoped Users

Applies a system-level deny permission on the namespace, which supports the Project-Scoped User Group. Members of the group receive limited visibility to organization-level data. For more information, see Manage your organization, Limit user visibility for projects and more.
ID: xxxxxxxx-aaaa-1111-bbbb-11111


PipelineCachePrivileges

Read
Write

Manages permissions to read and write pipeline cache entries. These permissions are only assigned to internal Azure DevOps service principles.
ID: xxxxxxxx-aaaa-1111-bbbb-11111


ReleaseManagement

ViewTaskEditor
ViewCDWorkflowEditor
ExportReleaseDefinition
ViewLegacyUI
DeploymentSummaryAcrossProjects
ViewExternalArtifactCommitsAndWorkItems

Manages access to Release Management user interface elements.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


SearchSecurity

ReadMembers ReadAnonymous

This security namespace is used to know if a user is valid or anonymous/public.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


ServiceHooks

ViewSubscriptions
EditSubscriptions
DeleteSubscriptions
PublishEvents

Manages permissions to view, edit, and delete service hook subscriptions and publish service hook events. These permissions are automatically assigned to members of the Project Collection Administrators group. DeleteSubscriptions is no longer used; EditSubscriptions can delete service hooks.

ID: xxxxxxxx-aaaa-1111-bbbb-11111


UtilizationPermissions

QueryUsageSummary

Manages permissions to query usage. By default, all members of the Project Collection Administrators groups and users granted Stakeholder access are granted permission to query usage summary for everyone. For more information, see Rate limits.

Token format: /
ID: xxxxxxxx-aaaa-1111-bbbb-11111


WorkItemTrackingAdministration

ManagePermissions
DestroyAttachments

Manages permissions for administrating work tracking and destroying attachments.
ID: xxxxxxxx-aaaa-1111-bbbb-11111


WorkItemTrackingProvision

Administer
ManageLinkTypes

Manages permissions for changing work tracking processes and managing link types. The WorkItemTrackingProvision namespace is an older security namespace that is mostly used for earlier on-premises versions. The Process namespace replaces this namespace for managing processes in Azure DevOps Server 2019 and later versions.

Root token format: /$
Token format for a specific project: $/PROJECT_ID

ID: xxxxxxxx-aaaa-1111-bbbb-11111


Deprecated and read-only namespaces

The following namespaces are either deprecated or read-only. Don't use them.

  • CrossProjectWidgetView
  • DataProvider
  • Favorites
  • Graph
  • Identity2
  • IdentityPicker
  • Job
  • Location
  • ProjectAnalysisLanguageMetrics
  • Proxy
  • Publish
  • Registry
  • Security
  • ServicingOrchestration
  • SettingEntries
  • Social
  • StrongBox
  • TeamLabSecurity
  • TestManagement
  • VersionControlItems2
  • ViewActivityPaneSecurity
  • WebPlatform
  • WorkItemsHub
  • WorkItemTracking
  • WorkItemTrackingConfiguration