Access Control Entries (ACEs)

Last Update: 3/21/2017

api-version = 1.0

Add a list of access control entries

Use this API to add or update ACEs in the ACL for the provided token. 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://{instance}/_apis/accesscontrolentries/{securitynamespace}/?api-version={version}
Parameter Type Default Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
securitynamespace guid ID of the security namespace.
Query
api-version string Version of the API to use.
Body
token string The token whose ACL should be modified.
aces AccessControlEntry[] The ACEs to set.
merge bool True to merge permission bits in case of a conflicting ACE; false to overwrite

No merge

The allow bit is set to 5 before the update.

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/accesscontrolentries/5a27515b-ccd7-42c9-84f1-54c998f03866/?api-version=1.0
Content-Type: application/json
{
  "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": {}
    }
  ]
}

With merge

The allow bit is set to 5 before the update.

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/accesscontrolentries/5a27515b-ccd7-42c9-84f1-54c998f03866/?api-version=1.0
Content-Type: application/json
{
  "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": {}
    }
  ]
}

Remove a list of access control entries

Use this API to remove the provided ACEs from the ACL belonging to the provided token.

DELETE https://{instance}/_apis/accesscontrolentries/{securitynamespace}/?api-version={version}&token={string}[&descriptors={string}]
Parameter Type Default Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
securitynamespace guid ID of the security namespace.
Query
api-version string Version of the API to use.
token string The token whose ACL should be modified.
descriptors string String containing a list of identity descriptors separated by ',' whose entries should be removed.

Remove ACEs

Any ACEs whose descriptor is in the provided descriptors list will be removed from the ACL.

Sample request

DELETE https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/accesscontrolentries/5a27515b-ccd7-42c9-84f1-54c998f03866/?token=newToken&descriptors=Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1,Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-2&api-version=1.0

Sample response

Status code: 200
true