Share via

Identities - Read Identities

  • Reference
Service:
Identities
API Version:
7.1

Resolve legacy identity information for use with older APIs such as the Security APIs

GET https://vssps.dev.azure.com/{organization}/_apis/identities?api-version=7.1
With optional parameters: 
GET https://vssps.dev.azure.com/{organization}/_apis/identities?descriptors={descriptors}&identityIds={identityIds}&subjectDescriptors={subjectDescriptors}&searchFilter={searchFilter}&filterValue={filterValue}&queryMembership={queryMembership}&api-version=7.1

URI Parameters

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

string

A comma separated list of identity descriptors to resolve
filterValue
 query

string

The search value, as specified by the searchFilter.
identityIds
 query

string

A comma seperated list of storage keys to resolve
queryMembership
 query

QueryMembership

The membership information to include with the identities. Values can be None for no membership data or Direct to include the groups that the identity is a member of and the identities that are a member of this identity (groups only)
searchFilter
 query

string

The type of search to perform. Values can be AccountName (domain\alias), DisplayName, MailAddress, General (display name, account name, or unique name), or LocalGroupName (only search Azure Devops groups).
subjectDescriptors
 query

string

A comma seperated list of subject descriptors to resolve

Responses

Name Type Description
200 OK

Identity[]

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.identity Grants the ability to read identities and groups.

Examples

By Email
By IdentityDescriptors
By Ids
By Name
By Subject Descriptors

By Email

Sample request

GET https://vssps.dev.azure.com/fabrikam/_apis/identities?searchFilter=General&filterValue=jtseng@vscsi.us&queryMembership=None&api-version=7.1

Sample response

Status code:
200 
{
  "count": 1,
  "value": [
    {
      "id": "81fa6389-0872-6fdd-a451-7ba7880f566a",
      "descriptor": "Microsoft.IdentityModel.Claims.ClaimsIdentity;7a394543-62fd-4274-a7d2-8fac775942b6\\jtseng@vscsi.us",
      "subjectDescriptor": "aad.MDA0NzBlMzQtZGE2MS03YTY5LWJkOTYtNDg3YTg0OWVjNTU4",
      "providerDisplayName": "Jia-hao Tseng",
      "isActive": true,
      "members": [],
      "memberOf": [],
      "memberIds": [],
      "properties": {
        "SchemaClassName": {
          "$type": "System.String",
          "$value": "User"
        },
        "Description": {
          "$type": "System.String",
          "$value": ""
        },
        "Domain": {
          "$type": "System.String",
          "$value": "7a394543-62fd-4274-a7d2-8fac775942b6"
        },
        "Account": {
          "$type": "System.String",
          "$value": "jtseng@vscsi.us"
        },
        "DN": {
          "$type": "System.String",
          "$value": ""
        },
        "Mail": {
          "$type": "System.String",
          "$value": "jtseng@vscsi.us"
        },
        "SpecialType": {
          "$type": "System.String",
          "$value": "Generic"
        },
        "Alias": {
          "$type": "System.String",
          "$value": "jtseng"
        },
        "PUID": {
          "$type": "System.String",
          "$value": "aad:100FAFF21C1B5261"
        },
        "ComplianceValidated": {
          "$type": "System.DateTime",
          "$value": "2020-04-23T00:00:00Z"
        },
        "http://schemas.microsoft.com/identity/claims/objectidentifier": {
          "$type": "System.String",
          "$value": "55c8c7b6-7ace-43bc-918f-304dfa2b6317"
        },
        "MetadataUpdateDate": {
          "$type": "System.DateTime",
          "$value": "2018-07-10T16:11:40Z"
        },
        "DirectoryAlias": {
          "$type": "System.String",
          "$value": "jtseng"
        }
      },
      "resourceVersion": 2,
      "metaTypeId": 0
    }
  ]
}

By IdentityDescriptors

Sample request

GET https://vssps.dev.azure.com/fabrikam/_apis/identities?descriptors=Microsoft.IdentityModel.Claims.ClaimsIdentity;7a394543-62fd-4274-a7d2-8fac775942b6\jtseng@vscsi.us,Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1725938060-2279921994-2555521242-2616350130-0-0-0-0-3&queryMembership=None&api-version=7.1

Sample response

Status code:
200 
{
  "count": 2,
  "value": [
    {
      "id": "81fa6389-0872-6fdd-a451-7ba7880f566a",
      "descriptor": "Microsoft.IdentityModel.Claims.ClaimsIdentity;7a394543-62fd-4274-a7d2-8fac775942b6\\jtseng@vscsi.us",
      "subjectDescriptor": "aad.MDA0NzBlMzQtZGE2MS03YTY5LWJkOTYtNDg3YTg0OWVjNTU4",
      "providerDisplayName": "Jia-hao Tseng",
      "isActive": true,
      "members": [],
      "memberOf": [],
      "memberIds": [],
      "properties": {
        "SchemaClassName": {
          "$type": "System.String",
          "$value": "User"
        },
        "Description": {
          "$type": "System.String",
          "$value": ""
        },
        "Domain": {
          "$type": "System.String",
          "$value": "7a394543-62fd-4274-a7d2-8fac775942b6"
        },
        "Account": {
          "$type": "System.String",
          "$value": "jtseng@vscsi.us"
        },
        "DN": {
          "$type": "System.String",
          "$value": ""
        },
        "Mail": {
          "$type": "System.String",
          "$value": "jtseng@vscsi.us"
        },
        "SpecialType": {
          "$type": "System.String",
          "$value": "Generic"
        },
        "Alias": {
          "$type": "System.String",
          "$value": "jtseng"
        },
        "PUID": {
          "$type": "System.String",
          "$value": "aad:100FAFF21C1B5261"
        },
        "ComplianceValidated": {
          "$type": "System.DateTime",
          "$value": "2020-04-23T00:00:00Z"
        },
        "http://schemas.microsoft.com/identity/claims/objectidentifier": {
          "$type": "System.String",
          "$value": "55c8c7b6-7ace-43bc-918f-304dfa2b6317"
        },
        "MetadataUpdateDate": {
          "$type": "System.DateTime",
          "$value": "2018-07-10T16:11:40Z"
        },
        "DirectoryAlias": {
          "$type": "System.String",
          "$value": "jtseng"
        }
      },
      "resourceVersion": 2,
      "metaTypeId": 0
    },
    {
      "id": "7c86b535-818b-423f-b0fd-19a2e9f32710",
      "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1725938060-2279921994-2555521242-2616350130-0-0-0-0-3",
      "subjectDescriptor": "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xNzI1OTM4MDYwLTIyNzk5MjE5OTQtMjU1NTUyMTI0Mi0yNjE2MzUwMTMwLTAtMC0wLTAtMw",
      "providerDisplayName": "[jtseng]\\Project Collection Valid Users",
      "isActive": true,
      "isContainer": true,
      "members": [],
      "memberOf": [],
      "memberIds": [],
      "properties": {
        "SchemaClassName": {
          "$type": "System.String",
          "$value": "Group"
        },
        "Description": {
          "$type": "System.String",
          "$value": "This application group contains all users and groups that have access to the Team Project Collection."
        },
        "Domain": {
          "$type": "System.String",
          "$value": "vstfs:///Framework/IdentityDomain/8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "Account": {
          "$type": "System.String",
          "$value": "Project Collection Valid Users"
        },
        "SecurityGroup": {
          "$type": "System.String",
          "$value": "SecurityGroup"
        },
        "SpecialType": {
          "$type": "System.String",
          "$value": "EveryoneApplicationGroup"
        },
        "ScopeId": {
          "$type": "System.Guid",
          "$value": "8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "ScopeType": {
          "$type": "System.String",
          "$value": "ServiceHost"
        },
        "LocalScopeId": {
          "$type": "System.Guid",
          "$value": "8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "SecuringHostId": {
          "$type": "System.Guid",
          "$value": "e26baa74-481c-42bc-a78c-f2a89decc807"
        },
        "ScopeName": {
          "$type": "System.String",
          "$value": "jtseng"
        },
        "GlobalScope": {
          "$type": "System.String",
          "$value": "GlobalScope"
        },
        "VirtualPlugin": {
          "$type": "System.String",
          "$value": ""
        }
      },
      "resourceVersion": 2,
      "metaTypeId": 255
    }
  ]
}

By Ids

Sample request

GET https://vssps.dev.azure.com/fabrikam/_apis/identities?identityIds=81fa638908726fdda4517ba7880f566a,7c86b535818b423fb0fd19a2e9f32710&queryMembership=None&api-version=7.1

Sample response

Status code:
200 
{
  "count": 2,
  "value": [
    {
      "id": "81fa6389-0872-6fdd-a451-7ba7880f566a",
      "descriptor": "Microsoft.IdentityModel.Claims.ClaimsIdentity;7a394543-62fd-4274-a7d2-8fac775942b6\\jtseng@vscsi.us",
      "subjectDescriptor": "aad.MDA0NzBlMzQtZGE2MS03YTY5LWJkOTYtNDg3YTg0OWVjNTU4",
      "providerDisplayName": "Jia-hao Tseng",
      "isActive": true,
      "members": [],
      "memberOf": [],
      "memberIds": [],
      "properties": {
        "SchemaClassName": {
          "$type": "System.String",
          "$value": "User"
        },
        "Description": {
          "$type": "System.String",
          "$value": ""
        },
        "Domain": {
          "$type": "System.String",
          "$value": "7a394543-62fd-4274-a7d2-8fac775942b6"
        },
        "Account": {
          "$type": "System.String",
          "$value": "jtseng@vscsi.us"
        },
        "DN": {
          "$type": "System.String",
          "$value": ""
        },
        "Mail": {
          "$type": "System.String",
          "$value": "jtseng@vscsi.us"
        },
        "SpecialType": {
          "$type": "System.String",
          "$value": "Generic"
        },
        "Alias": {
          "$type": "System.String",
          "$value": "jtseng"
        },
        "PUID": {
          "$type": "System.String",
          "$value": "aad:100FAFF21C1B5261"
        },
        "ComplianceValidated": {
          "$type": "System.DateTime",
          "$value": "2020-04-23T00:00:00Z"
        },
        "http://schemas.microsoft.com/identity/claims/objectidentifier": {
          "$type": "System.String",
          "$value": "55c8c7b6-7ace-43bc-918f-304dfa2b6317"
        },
        "MetadataUpdateDate": {
          "$type": "System.DateTime",
          "$value": "2018-07-10T16:11:40Z"
        },
        "DirectoryAlias": {
          "$type": "System.String",
          "$value": "jtseng"
        }
      },
      "resourceVersion": 2,
      "metaTypeId": 0
    },
    {
      "id": "7c86b535-818b-423f-b0fd-19a2e9f32710",
      "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1725938060-2279921994-2555521242-2616350130-0-0-0-0-3",
      "subjectDescriptor": "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xNzI1OTM4MDYwLTIyNzk5MjE5OTQtMjU1NTUyMTI0Mi0yNjE2MzUwMTMwLTAtMC0wLTAtMw",
      "providerDisplayName": "[jtseng]\\Project Collection Valid Users",
      "isActive": true,
      "isContainer": true,
      "members": [],
      "memberOf": [],
      "memberIds": [],
      "properties": {
        "SchemaClassName": {
          "$type": "System.String",
          "$value": "Group"
        },
        "Description": {
          "$type": "System.String",
          "$value": "This application group contains all users and groups that have access to the Team Project Collection."
        },
        "Domain": {
          "$type": "System.String",
          "$value": "vstfs:///Framework/IdentityDomain/8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "Account": {
          "$type": "System.String",
          "$value": "Project Collection Valid Users"
        },
        "SecurityGroup": {
          "$type": "System.String",
          "$value": "SecurityGroup"
        },
        "SpecialType": {
          "$type": "System.String",
          "$value": "EveryoneApplicationGroup"
        },
        "ScopeId": {
          "$type": "System.Guid",
          "$value": "8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "ScopeType": {
          "$type": "System.String",
          "$value": "ServiceHost"
        },
        "LocalScopeId": {
          "$type": "System.Guid",
          "$value": "8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "SecuringHostId": {
          "$type": "System.Guid",
          "$value": "e26baa74-481c-42bc-a78c-f2a89decc807"
        },
        "ScopeName": {
          "$type": "System.String",
          "$value": "jtseng"
        },
        "GlobalScope": {
          "$type": "System.String",
          "$value": "GlobalScope"
        },
        "VirtualPlugin": {
          "$type": "System.String",
          "$value": ""
        }
      },
      "resourceVersion": 2,
      "metaTypeId": 255
    }
  ]
}

By Name

Sample request

GET https://vssps.dev.azure.com/fabrikam/_apis/identities?searchFilter=General&filterValue=Project Collection Valid Users&queryMembership=None&api-version=7.1

Sample response

Status code:
200 
{
  "count": 1,
  "value": [
    {
      "id": "7c86b535-818b-423f-b0fd-19a2e9f32710",
      "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1725938060-2279921994-2555521242-2616350130-0-0-0-0-3",
      "subjectDescriptor": "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xNzI1OTM4MDYwLTIyNzk5MjE5OTQtMjU1NTUyMTI0Mi0yNjE2MzUwMTMwLTAtMC0wLTAtMw",
      "providerDisplayName": "[jtseng]\\Project Collection Valid Users",
      "isActive": true,
      "isContainer": true,
      "members": [],
      "memberOf": [],
      "memberIds": [],
      "properties": {
        "SchemaClassName": {
          "$type": "System.String",
          "$value": "Group"
        },
        "Description": {
          "$type": "System.String",
          "$value": "This application group contains all users and groups that have access to the Team Project Collection."
        },
        "Domain": {
          "$type": "System.String",
          "$value": "vstfs:///Framework/IdentityDomain/8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "Account": {
          "$type": "System.String",
          "$value": "Project Collection Valid Users"
        },
        "SecurityGroup": {
          "$type": "System.String",
          "$value": "SecurityGroup"
        },
        "SpecialType": {
          "$type": "System.String",
          "$value": "EveryoneApplicationGroup"
        },
        "ScopeId": {
          "$type": "System.Guid",
          "$value": "8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "ScopeType": {
          "$type": "System.String",
          "$value": "ServiceHost"
        },
        "LocalScopeId": {
          "$type": "System.Guid",
          "$value": "8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "SecuringHostId": {
          "$type": "System.Guid",
          "$value": "e26baa74-481c-42bc-a78c-f2a89decc807"
        },
        "ScopeName": {
          "$type": "System.String",
          "$value": "jtseng"
        },
        "GlobalScope": {
          "$type": "System.String",
          "$value": "GlobalScope"
        },
        "VirtualPlugin": {
          "$type": "System.String",
          "$value": ""
        }
      },
      "resourceVersion": 2,
      "metaTypeId": 255
    }
  ]
}

By Subject Descriptors

Sample request

GET https://vssps.dev.azure.com/fabrikam/_apis/identities?subjectDescriptors=aad.MDA0NzBlMzQtZGE2MS03YTY5LWJkOTYtNDg3YTg0OWVjNTU4,vssgp.Uy0xLTktMTU1MTM3NDI0NS0xNzI1OTM4MDYwLTIyNzk5MjE5OTQtMjU1NTUyMTI0Mi0yNjE2MzUwMTMwLTAtMC0wLTAtMw&queryMembership=None&api-version=7.1

Sample response

Status code:
200 
{
  "count": 2,
  "value": [
    {
      "id": "81fa6389-0872-6fdd-a451-7ba7880f566a",
      "descriptor": "Microsoft.IdentityModel.Claims.ClaimsIdentity;7a394543-62fd-4274-a7d2-8fac775942b6\\jtseng@vscsi.us",
      "subjectDescriptor": "aad.MDA0NzBlMzQtZGE2MS03YTY5LWJkOTYtNDg3YTg0OWVjNTU4",
      "providerDisplayName": "Jia-hao Tseng",
      "isActive": true,
      "members": [],
      "memberOf": [],
      "memberIds": [],
      "properties": {
        "SchemaClassName": {
          "$type": "System.String",
          "$value": "User"
        },
        "Description": {
          "$type": "System.String",
          "$value": ""
        },
        "Domain": {
          "$type": "System.String",
          "$value": "7a394543-62fd-4274-a7d2-8fac775942b6"
        },
        "Account": {
          "$type": "System.String",
          "$value": "jtseng@vscsi.us"
        },
        "DN": {
          "$type": "System.String",
          "$value": ""
        },
        "Mail": {
          "$type": "System.String",
          "$value": "jtseng@vscsi.us"
        },
        "SpecialType": {
          "$type": "System.String",
          "$value": "Generic"
        },
        "Alias": {
          "$type": "System.String",
          "$value": "jtseng"
        },
        "PUID": {
          "$type": "System.String",
          "$value": "aad:100FAFF21C1B5261"
        },
        "ComplianceValidated": {
          "$type": "System.DateTime",
          "$value": "2020-04-23T00:00:00Z"
        },
        "http://schemas.microsoft.com/identity/claims/objectidentifier": {
          "$type": "System.String",
          "$value": "55c8c7b6-7ace-43bc-918f-304dfa2b6317"
        },
        "MetadataUpdateDate": {
          "$type": "System.DateTime",
          "$value": "2018-07-10T16:11:40Z"
        },
        "DirectoryAlias": {
          "$type": "System.String",
          "$value": "jtseng"
        }
      },
      "resourceVersion": 2,
      "metaTypeId": 0
    },
    {
      "id": "7c86b535-818b-423f-b0fd-19a2e9f32710",
      "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1725938060-2279921994-2555521242-2616350130-0-0-0-0-3",
      "subjectDescriptor": "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xNzI1OTM4MDYwLTIyNzk5MjE5OTQtMjU1NTUyMTI0Mi0yNjE2MzUwMTMwLTAtMC0wLTAtMw",
      "providerDisplayName": "[jtseng]\\Project Collection Valid Users",
      "isActive": true,
      "isContainer": true,
      "members": [],
      "memberOf": [],
      "memberIds": [],
      "properties": {
        "SchemaClassName": {
          "$type": "System.String",
          "$value": "Group"
        },
        "Description": {
          "$type": "System.String",
          "$value": "This application group contains all users and groups that have access to the Team Project Collection."
        },
        "Domain": {
          "$type": "System.String",
          "$value": "vstfs:///Framework/IdentityDomain/8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "Account": {
          "$type": "System.String",
          "$value": "Project Collection Valid Users"
        },
        "SecurityGroup": {
          "$type": "System.String",
          "$value": "SecurityGroup"
        },
        "SpecialType": {
          "$type": "System.String",
          "$value": "EveryoneApplicationGroup"
        },
        "ScopeId": {
          "$type": "System.Guid",
          "$value": "8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "ScopeType": {
          "$type": "System.String",
          "$value": "ServiceHost"
        },
        "LocalScopeId": {
          "$type": "System.Guid",
          "$value": "8cb9df66-e487-4ad9-9852-28da9bf255b2"
        },
        "SecuringHostId": {
          "$type": "System.Guid",
          "$value": "e26baa74-481c-42bc-a78c-f2a89decc807"
        },
        "ScopeName": {
          "$type": "System.String",
          "$value": "jtseng"
        },
        "GlobalScope": {
          "$type": "System.String",
          "$value": "GlobalScope"
        },
        "VirtualPlugin": {
          "$type": "System.String",
          "$value": ""
        }
      },
      "resourceVersion": 2,
      "metaTypeId": 255
    }
  ]
}

Definitions

Name Description
Identity
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.
PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.
QueryMembership

Identity

Name Type Description
customDisplayName

string

The custom display name for the identity (if any). Setting this property to an empty string will clear the existing custom display name. Setting this property to null will not affect the existing persisted value (since null values do not get sent over the wire or to the database)
descriptor

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

string

Identity Identifier. Also called Storage Key, or VSID
isActive

boolean

True if the identity has a membership in any Azure Devops group in the organization.
isContainer

boolean

True if the identity is a group.
masterId

string

memberIds

string[]

Id of the members of the identity (groups only).
memberOf

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

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

integer

properties

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.
providerDisplayName

string

The display name for the identity as specified by the source identity provider.
resourceVersion

integer

socialDescriptor

string

subjectDescriptor

string

Subject descriptor of a Graph entity.
uniqueUserId

integer

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

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

Name Type Description
count

integer

The count of properties in the collection.
item

object

keys

string[]

The set of keys in the collection.
values

string[]

The set of values in the collection.

QueryMembership

Name Type Description
direct

string

Query will return only direct membership data
expanded

string

Query will return expanded membership data
expandedDown

string

Query will return expanded down membership data (children only)
expandedUp

string

Query will return expanded up membership data (parents only)
none

string

Query will not return any membership data