Access Control Lists - Query
Return a list of access control lists for the specified security namespace and token. All ACLs in the security namespace will be retrieved if no optional parameters are provided.
GET https://dev.azure.com/{organization}/_apis/accesscontrollists/{securityNamespaceId}?api-version=5.0GET https://dev.azure.com/{organization}/_apis/accesscontrollists/{securityNamespaceId}?token={token}&descriptors={descriptors}&includeExtendedInfo={includeExtendedInfo}&recurse={recurse}&api-version=5.0URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
security
|
path | True |
string uuid |
Security namespace identifier. |
|
organization
|
path |
string |
The name of the Azure DevOps organization. |
|
|
api-version
|
query | True |
string |
Version of the API to use. This should be set to '5.0' to use this version of the api. |
|
descriptors
|
query |
string |
An optional filter string containing a list of identity descriptors separated by ',' whose ACEs should be retrieved. If this is left null, entire ACLs will be returned. |
|
|
include
|
query |
boolean |
If true, populate the extended information properties for the access control entries contained in the returned lists. |
|
|
recurse
|
query |
boolean |
If true and this is a hierarchical namespace, return child ACLs of the specified token. |
|
|
token
|
query |
string |
Security token |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
successful operation |
Security
accessToken
Personal access token. Use any value for the user name and the token as the password.
Type:
basic
Examples
| All ACLs in a security namespace |
| Filter by descriptors |
| Filter by token |
| Include child ACLs |
| Include extended info properties |
All ACLs in a security namespace
Sample Request
GET https://dev.azure.com/fabrikam/_apis/accesscontrollists/5a27515b-ccd7-42c9-84f1-54c998f03866?api-version=5.0
Sample Response
{
"count": 5,
"value": [
{
"inheritPermissions": true,
"token": "1ba198c0-7a12-46ed-a96b-f4e77554c6d4",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 31,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2",
"allow": 31,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-3": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-3",
"allow": 1,
"deny": 0
}
}
},
{
"inheritPermissions": true,
"token": "1ba198c0-7a12-46ed-a96b-f4e77554c6d4\\846cd9c3-56ba-4158-b6d2-23a3a73244e5",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-1-2": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-1-2",
"allow": 8,
"deny": 0
}
}
},
{
"inheritPermissions": true,
"token": "28b9bb88-a513-4115-9b5c-8be39ce1f1ba",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-2294004008-329585985-2606533603-2632053178-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-2294004008-329585985-2606533603-2632053178-0-0-0-0-1",
"allow": 31,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-2294004008-329585985-2606533603-2632053178-0-0-0-0-2": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-2294004008-329585985-2606533603-2632053178-0-0-0-0-2",
"allow": 31,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-2294004008-329585985-2606533603-2632053178-0-0-0-0-3": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-2294004008-329585985-2606533603-2632053178-0-0-0-0-3",
"allow": 1,
"deny": 0
}
}
},
{
"inheritPermissions": false,
"token": "token1",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 31,
"deny": 0
}
}
},
{
"inheritPermissions": false,
"token": "token2",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 1,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2",
"allow": 8,
"deny": 0
}
}
}
]
}Filter by descriptors
Sample Request
GET https://dev.azure.com/fabrikam/_apis/accesscontrollists/5a27515b-ccd7-42c9-84f1-54c998f03866?descriptors=Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1&api-version=5.0
Sample Response
{
"count": 5,
"value": [
{
"inheritPermissions": true,
"token": "1ba198c0-7a12-46ed-a96b-f4e77554c6d4",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 31,
"deny": 0
}
}
},
{
"inheritPermissions": true,
"token": "1ba198c0-7a12-46ed-a96b-f4e77554c6d4\\846cd9c3-56ba-4158-b6d2-23a3a73244e5",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 0,
"deny": 0
}
}
},
{
"inheritPermissions": true,
"token": "28b9bb88-a513-4115-9b5c-8be39ce1f1ba",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 0,
"deny": 0
}
}
},
{
"inheritPermissions": false,
"token": "token1",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 31,
"deny": 0
}
}
},
{
"inheritPermissions": false,
"token": "token2",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 1,
"deny": 0
}
}
}
]
}Filter by token
Sample Request
GET https://dev.azure.com/fabrikam/_apis/accesscontrollists/5a27515b-ccd7-42c9-84f1-54c998f03866?token=1ba198c0-7a12-46ed-a96b-f4e77554c6d4&api-version=5.0
Sample Response
{
"count": 1,
"value": [
{
"inheritPermissions": true,
"token": "1ba198c0-7a12-46ed-a96b-f4e77554c6d4",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 31,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2",
"allow": 31,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-3": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-3",
"allow": 1,
"deny": 0
}
}
}
]
}Include child ACLs
Sample Request
GET https://dev.azure.com/fabrikam/_apis/accesscontrollists/5a27515b-ccd7-42c9-84f1-54c998f03866?token=1ba198c0-7a12-46ed-a96b-f4e77554c6d4&includeExtendedInfo=False&recurse=True&api-version=5.0
Sample Response
{
"count": 2,
"value": [
{
"inheritPermissions": true,
"token": "1ba198c0-7a12-46ed-a96b-f4e77554c6d4",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 31,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2",
"allow": 31,
"deny": 0
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-3": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-3",
"allow": 1,
"deny": 0
}
}
},
{
"inheritPermissions": true,
"token": "1ba198c0-7a12-46ed-a96b-f4e77554c6d4\\846cd9c3-56ba-4158-b6d2-23a3a73244e5",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-1-2": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-1-2",
"allow": 8,
"deny": 0
}
}
}
]
}Include extended info properties
Sample Request
GET https://dev.azure.com/fabrikam/_apis/accesscontrollists/5a27515b-ccd7-42c9-84f1-54c998f03866?token=1ba198c0-7a12-46ed-a96b-f4e77554c6d4&includeExtendedInfo=True&api-version=5.0
Sample Response
{
"count": 1,
"value": [
{
"inheritPermissions": true,
"token": "1ba198c0-7a12-46ed-a96b-f4e77554c6d4",
"acesDictionary": {
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
"allow": 31,
"deny": 0,
"extendedInfo": {
"effectiveAllow": 31
}
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2",
"allow": 31,
"deny": 0,
"extendedInfo": {
"effectiveAllow": 31
}
},
"Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-3": {
"descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-3",
"allow": 1,
"deny": 0,
"extendedInfo": {
"effectiveAllow": 1
}
}
},
"includeExtendedInfo": true
}
]
}Definitions
| Name | Description |
|---|---|
|
Access |
Class for encapsulating the allowed and denied permissions for a given IdentityDescriptor. |
|
Access |
The AccessControlList class is meant to associate a set of AccessControlEntries with a security token and its inheritance settings. |
|
Ace |
Holds the inherited and effective permission information for a given AccessControlEntry. |
|
Identity |
An Identity descriptor is a wrapper for the identity type (Windows SID, Passport) along with a unique identifier such as the SID or PUID. |
AccessControlEntry
Class for encapsulating the allowed and denied permissions for a given IdentityDescriptor.
| Name | Type | Description |
|---|---|---|
| allow |
integer |
The set of permission bits that represent the actions that the associated descriptor is allowed to perform. |
| deny |
integer |
The set of permission bits that represent the actions that the associated descriptor is not allowed to perform. |
| descriptor |
The descriptor for the user this AccessControlEntry applies to. |
|
| extendedInfo |
This value, when set, reports the inherited and effective information for the associated descriptor. This value is only set on AccessControlEntries returned by the QueryAccessControlList(s) call when its includeExtendedInfo parameter is set to true. |
AccessControlList
The AccessControlList class is meant to associate a set of AccessControlEntries with a security token and its inheritance settings.
| Name | Type | Description |
|---|---|---|
| acesDictionary |
<string,
Access |
Storage of permissions keyed on the identity the permission is for. |
| includeExtendedInfo |
boolean |
True if this ACL holds ACEs that have extended information. |
| inheritPermissions |
boolean |
True if the given token inherits permissions from parents. |
| token |
string |
The token that this AccessControlList is for. |
AceExtendedInformation
Holds the inherited and effective permission information for a given AccessControlEntry.
| Name | Type | Description |
|---|---|---|
| effectiveAllow |
integer |
This is the combination of all of the explicit and inherited permissions for this identity on this token. These are the permissions used when determining if a given user has permission to perform an action. |
| effectiveDeny |
integer |
This is the combination of all of the explicit and inherited permissions for this identity on this token. These are the permissions used when determining if a given user has permission to perform an action. |
| inheritedAllow |
integer |
These are the permissions that are inherited for this identity on this token. If the token does not inherit permissions this will be 0. Note that any permissions that have been explicitly set on this token for this identity, or any groups that this identity is a part of, are not included here. |
| inheritedDeny |
integer |
These are the permissions that are inherited for this identity on this token. If the token does not inherit permissions this will be 0. Note that any permissions that have been explicitly set on this token for this identity, or any groups that this identity is a part of, are not included here. |
IdentityDescriptor
An Identity descriptor is a wrapper for the identity type (Windows SID, Passport) along with a unique identifier such as the SID or PUID.
| Name | Type | Description |
|---|---|---|
| identifier |
string |
The unique identifier for this identity, not exceeding 256 chars, which will be persisted. |
| identityType |
string |
Type of descriptor (for example, Windows, Passport, etc.). |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for