Permissions and security

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 1.0

Evaluate permissions

Use this API to evaluate whether the calling identity has the requested permissions to a token or set of tokens. If the alwaysAllowAdministrators flag is set, then members of the Administrators group for the service host containing the namespace (i.e. 'Project Collection Administrators' or 'Organization Administrators') will always pass the security check.

Evaluate permissions on a single token

GET https://{instance}/_apis/permissions/{securitynamespace}/{permissions}/?api-version={version}&token={string}&alwaysAllowAdministrators={bool}

Parameter	Type	Default	Notes
URL
instance	string		TFS server name ({server:port}).
securitynamespace	guid		ID of the security namespace.
permissions	int		The permission bits to demand.
Query
api-version	string		Version of the API to use.
token	string		The token on which to check permissions.
alwaysAllowAdministrators	bool		True if members of the Administrators group should always pass the security check.

AlwaysAllowAdministrators set to false

Sample request

GET https://mytfsserver/DefaultCollection/_apis/permissions/5a27515b-ccd7-42c9-84f1-54c998f03866/8/?token=token1&alwaysAllowAdministrators=False&api-version=1.0

AlwaysAllowAdministrators set to true

Sample request

GET https://mytfsserver/DefaultCollection/_apis/permissions/5a27515b-ccd7-42c9-84f1-54c998f03866/8/?token=token1&alwaysAllowAdministrators=True&api-version=1.0

Sample response

true

Evaluate permissions on a list of tokens

Permissions evaluation on a list of tokens does not aggregate the results, nor does it short-circuit if one of the evaluations yields a false result.

There are two versions of this API.

Plural version

This version of the API is just the plural version of permission check on a single token.

GET https://{instance}/_apis/permissions/{securitynamespace}/{permissions}/?api-version={version}&tokens={string}&alwaysAllowAdministrators={bool}&delimiter={char}

Parameter	Type	Default	Notes
URL
instance	string		TFS server name ({server:port}).
securitynamespace	guid		ID of the security namespace.
permissions	int		The permission bits to demand.
Query
api-version	string		Version of the API to use. Works with Version 2.2 and above.
tokens	string		String containing a list of tokens (separated by the delimiter) on which to check permissions.
alwaysAllowAdministrators	bool		True if members of the Administrators group should always pass the security check.
delimiter	char	,	The delimiter to use when encoding the list of tokens on the wire as a single string.

Sample request

GET https://mytfsserver/DefaultCollection/_apis/permissions/5a27515b-ccd7-42c9-84f1-54c998f03866/8/?api-version=2.2&tokens=token1,token2,token3&alwaysAllowAdministrators=False

Sample response

{
  "count": 3,
  "value": [
    false,
    false,
    true
  ]
}

Batch version

This version of the API performs a batch of "has permission" checks.

POST https://{instance}/_apis/security/permissionevaluationbatch/?api-version={version}

Parameter	Type	Default	Notes
URL
instance	string		TFS server name ({server:port}).
Query
api-version	string		Version of the API to use. Works with Version 3.0 and above.
Body
alwaysAllowAdministrators	bool		True if members of the Administrators group should always pass the security check.
evaluations	PermissionEvaluation[]		Array of evaluation requests.

Each PermissionEvaluation contains:

Parameter	Type	Notes
securitynamespace	guid	Security namespace identifier for this permission evaluation.
token	string	Security namespace-specific token for this permission evaluation.
permissions	int	The permission bits to demand.
value	bool	[Out] The result of the security evaluation.

Sample request

POST https://mytfsserver/DefaultCollection/_apis/security/permissionevaluationbatch/?api-version=3.0-preview

{
  "alwaysallowadministrators": false,
  "evaluations": [
    {
      "securitynamespaceid": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token1",
      "permissions": 8
    },
    {
      "securitynamespaceid": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token2",
      "permissions": 8
    },
    {
      "securitynamespaceid": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token3",
      "permissions": 8
    }
  ]
}

Sample response

{
  "evaluations": [
    {
      "securityNamespaceId": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token1",
      "permissions": 8,
      "value": false
    },
    {
      "securityNamespaceId": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token2",
      "permissions": 8,
      "value": false
    },
    {
      "securityNamespaceId": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token3",
      "permissions": 8,
      "value": true
    }
  ]
}

Remove permissions

Removes the specified bits from the allow and deny values for the ACE with the given identity descriptor in the ACL for the given token. If no ACE for the given identity descriptor is found, no change is made.

DELETE https://{instance}/_apis/permissions/{securitynamespace}/{permissions}/?token={string}&descriptor={IdentityDescriptor}

Parameter	Type	Default	Notes
URL
instance	string		TFS server name ({server:port}).
securitynamespace	guid		ID of the security namespace.
permissions	int		The permission bits to remove from the ACE's allow and deny bitmasks.
Query
token	string		The token whose ACL contains the ACE to be modified.
descriptor	IdentityDescriptor		The descriptor of the ACE to be modified.

Sample request

DELETE https://mytfsserver/DefaultCollection/_apis/permissions/5a27515b-ccd7-42c9-84f1-54c998f03866/4/?token=token1&descriptor=Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1&api-version=1.0

Sample response

{
  "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
  "allow": 1,
  "deny": 0
}