Access Control Entries - Set Access Control Entries

Service:

Security

API Version:

5.1

Add or update ACEs in the ACL for the provided token. The request body contains the target token, a list of ACEs and a optional merge parameter. In the case of a collision (by identity descriptor) with an existing ACE in the ACL, the "merge" parameter determines the behavior. If set, the existing ACE has its allow and deny merged with the incoming ACE's allow and deny. If unset, the existing ACE is displaced.

POST https://dev.azure.com/{organization}/_apis/accesscontrolentries/{securityNamespaceId}?api-version=5.1

URI Parameters

Name	In	Required	Type	Description
securityNamespaceId	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.1' to use this version of the api.

Request Body

Name	Type	Description
item	string
type	string	Gets the node type for this JToken.

Responses

Name	Type	Description
200 OK	AccessControlEntry[]	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.security_manage	Grants the ability to read, write, and manage security permissions.

Examples

Merge

Replace

Merge

Sample Request

HTTP

POST https://dev.azure.com/fabrikam/_apis/accesscontrolentries/5a27515b-ccd7-42c9-84f1-54c998f03866?api-version=5.1

{
  "token": "newToken",
  "merge": true,
  "accessControlEntries": [
    {
      "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2",
      "allow": 8,
      "deny": 0,
      "extendedinfo": {}
    }
  ]
}

Sample Response

Status code:

200

{
  "count": 1,
  "value": [
    {
      "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2",
      "allow": 13,
      "deny": 0,
      "extendedInfo": {}
    }
  ]
}

Replace

Sample Request

HTTP

POST https://dev.azure.com/fabrikam/_apis/accesscontrolentries/5a27515b-ccd7-42c9-84f1-54c998f03866?api-version=5.1

{
  "token": "newToken",
  "merge": false,
  "accessControlEntries": [
    {
      "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
      "allow": 8,
      "deny": 0,
      "extendedinfo": {}
    }
  ]
}

Sample Response

Status code:

200

{
  "count": 1,
  "value": [
    {
      "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
      "allow": 8,
      "deny": 0,
      "extendedInfo": {}
    }
  ]
}

Definitions

Name	Description
AccessControlEntry	Class for encapsulating the allowed and denied permissions for a given IdentityDescriptor.
AceExtendedInformation	Holds the inherited and effective permission information for a given AccessControlEntry.
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.
JObject	Represents a JSON object.

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	IdentityDescriptor	The descriptor for the user this AccessControlEntry applies to.
extendedInfo	AceExtendedInformation	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.

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.).

JObject

Represents a JSON object.

Name	Type	Description
item	string
type	string	Gets the node type for this JToken.