Tokens

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.

Tokens are arbitrary strings representing resources in Team Services and Team Foundation Server. Resources are secured by associating access control lists (ACLs) with tokens. This article contains the format and examples for tokens representing different resource types.

The token format differs per resource type, however hierarchy and separator characters are common between all tokens.

Hierarchy

• A security namespace can be either hierarchical or flat.
• Tokens in a hierarchical namespace exist in a hierarchy with effective permissions being inherited from parent tokens to child tokens.
• Tokens in a flat namespace have no concept of a parent-child relationship between any two tokens.

Separator character

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

In addition to hierarchy and separator characters the contents of tokens vary depending on the needs of the resource.

Git repositories and branches

Token attributes

Attribute	Value
Hierarchical	true
Separator	/
Token root	repoV2

Token format and example

Format: repoV2/[{projectId}/[{repoId}/[{refNamespace}/[{encodedRef}/]]]]
Example: repoV2/212d1460-2143-4296-9771-c54336dbf3d3/393d8e86-ed2b-473f-8480-0cf728c1f866/refs/heads/6d0061007300740065007200/

Token parameters

Parameter	Required	Type	Notes
projectId	false	GUID	required if passing a repoId
repoId	false	GUID	required if passing a ref
refNamespace	false	string	required if passing a ref, see below for valid values
encodedRef	false	string	see below for encoding algorithm

Valid tokens always end in the separator character: '/'.

Ref namespaces

There are three valid ref namespaces:

• refs/heads - Git branches
• refs/tags - lightweight tags
• refs/notes - notes

Ref namespaces must be all lowercase.

Ref name encoding

Security tokens are case-insensitive, but Git refs are case-sensitive. Ref names are encoded to allow "master", "Master", and "MASTER" to be protected by different tokens.

To encode a ref name, each non-slash is converted to a string of the character's hexadecimal value. Slashes are preserved as-is. Input characters are C# strings, which means they are UTF-16 little-endian. For instance, in UTF-16 the character "m" is represented by the bytes 0x6d00. Thus, when encoding the branch "master", the first four characters are "6d00".

Check out the Git repo token blog post for more information on ref name encoding, including Python and C# code samples.

Token examples

For each of these examples, assume a projectId of 212d1460-2143-4296-9771-c54336dbf3d3 and a repoId of 393d8e86-ed2b-473f-8480-0cf728c1f866.

Securable resource	Token
All repos in the entire account/collection	repoV2/
All repos in the project	repoV2/212d1460-2143-4296-9771-c54336dbf3d3/
All refs in the repo	repoV2/212d1460-2143-4296-9771-c54336dbf3d3/393d8e86-ed2b-473f-8480-0cf728c1f866/
All branches in the repo	repoV2/212d1460-2143-4296-9771-c54336dbf3d3/393d8e86-ed2b-473f-8480-0cf728c1f866/refs/heads/
All tags in the repo	repoV2/212d1460-2143-4296-9771-c54336dbf3d3/393d8e86-ed2b-473f-8480-0cf728c1f866/refs/tags/
The main branch	repoV2/212d1460-2143-4296-9771-c54336dbf3d3/393d8e86-ed2b-473f-8480-0cf728c1f866/refs/heads/6d0061007300740065007200/
Any branch under "user/"	repoV2/212d1460-2143-4296-9771-c54336dbf3d3/393d8e86-ed2b-473f-8480-0cf728c1f866/refs/heads/7500730065007200/
Any branch under "user/totten/"	repoV2/212d1460-2143-4296-9771-c54336dbf3d3/393d8e86-ed2b-473f-8480-0cf728c1f866/refs/heads/7500730065007200/74006f007400740065006e00/