CommunicationIdentityClient (preview:2025-03-02)

2025/04/30 • 16 new methods

CommunicationIdentity_Create (new)
Description :  Create a new identity with an optional customId mapping, and optionally, an access token. If called again with the same customId, the returned identity will be the same as the one returned previously.
Reference :  Link ¶

⚼ Request

POST:  /identities
{
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
body:
{
Description: Additional options to return an access token, and to map with a custom id that is meaningful to you. ,
Required: False ,
}
{
customId:
{
Description: Set to tag the identity with your own id, Maximum length is 256 characters. ,
Required: False ,
}
string ,
createTokenWithScopes:
{
Description: Also create access token for the created identity. ,
Required: False ,
}
[
string ,
]
,
expiresInMinutes:
{
Description: Optional custom validity period of the token within [60,1440] minutes range. If not provided, the default value of 1440 minutes (24 hours) will be used. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (201)

{
identity:
{
Description: A communication identity. ,
Required: True ,
}
{
customId:
{
Description: The custom Id if one has been associated with the identity. ,
Required: False ,
}
string ,
lastTokenIssuedAt:
{
Description: Last time a token has been issued for the identity. ,
Format: date-time ,
Required: False ,
}
string ,
id:
{
Description: Identifier of the identity. ,
Required: True ,
}
string ,
}
,
accessToken:
{
Description: An access token. ,
Required: False ,
}
{
token:
{
Description: The access token issued for the identity. ,
Required: True ,
}
string ,
expiresOn:
{
Description: The expiry time of the token. ,
Format: date-time ,
Required: True ,
}
string ,
}
,
}
CommunicationIdentity_Delete (new)
Description :  Delete the identity, revoke all tokens for the identity and delete all associated data.
Reference :  Link ¶

⚼ Request

DELETE:  /identities/{id}
{
id:
{
Description: Identifier of the identity to be deleted. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (204)

{}
CommunicationIdentity_Get (new)
Description :  Get an identity by its id.
Reference :  Link ¶

⚼ Request

GET:  /identities/{id}
{
id:
{
Description: Identifier of the identity. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
customId:
{
Description: The custom Id if one has been associated with the identity. ,
Required: False ,
}
string ,
lastTokenIssuedAt:
{
Description: Last time a token has been issued for the identity. ,
Format: date-time ,
Required: False ,
}
string ,
id:
{
Description: Identifier of the identity. ,
Required: True ,
}
string ,
}
CommunicationIdentity_RevokeAccessTokens (new)
Description :  Revoke all access tokens for the specific identity.
Reference :  Link ¶

⚼ Request

POST:  /identities/{id}/:revokeAccessTokens
{
id:
{
Description: Identifier of the identity. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (204)

{}
CommunicationIdentity_ExchangeTeamsUserAccessToken (new)
Description :  Exchange an Entra ID access token of a Teams user for a new Communication Identity access token with a matching expiration time.
Reference :  Link ¶

⚼ Request

POST:  /teamsUser/:exchangeAccessToken
{
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
body:
{
Description: Request payload for the token exchange. ,
Required: True ,
}
{
token:
{
Description: Entra ID access token of a Teams User to acquire a new Communication Identity access token. ,
Required: True ,
}
string ,
appId:
{
Description: Client ID of an Entra ID application to be verified against the appid claim in the Entra ID access token. ,
Required: True ,
}
string ,
userId:
{
Description: Object ID of an Entra ID user (Teams User) to be verified against the oid claim in the Entra ID access token. ,
Required: True ,
}
string ,
}
,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
token:
{
Description: The access token issued for the identity. ,
Required: True ,
}
string ,
expiresOn:
{
Description: The expiry time of the token. ,
Format: date-time ,
Required: True ,
}
string ,
}
CommunicationIdentity_IssueAccessToken (new)
Description :  Issue a new token for an identity.
Reference :  Link ¶

⚼ Request

POST:  /identities/{id}/:issueAccessToken
{
id:
{
Description: Identifier of the identity to issue token for. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
body:
{
Description: Requested scopes for the new token. ,
Required: True ,
}
{
scopes:
{
Description: List of scopes attached to the token. ,
Required: True ,
}
[
string ,
]
,
expiresInMinutes:
{
Description: Optional custom validity period of the token within [60,1440] minutes range. If not provided, the default value of 1440 minutes (24 hours) will be used. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
token:
{
Description: The access token issued for the identity. ,
Required: True ,
}
string ,
expiresOn:
{
Description: The expiry time of the token. ,
Format: date-time ,
Required: True ,
}
string ,
}
TeamsExtensionToken_Exchange (new)
Description :  Exchanges a Teams Phone token for an ACS user access token.
Reference :  Link ¶

⚼ Request

POST:  /access/teamsExtension/:exchangeAccessToken
{
body:
{
Description: Request payload for the token exchange. ,
Required: True ,
}
object ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
identity:
{
Description: A communication identity. ,
Required: True ,
}
{
customId:
{
Description: The custom Id if one has been associated with the identity. ,
Required: False ,
}
string ,
lastTokenIssuedAt:
{
Description: Last time a token has been issued for the identity. ,
Format: date-time ,
Required: False ,
}
string ,
id:
{
Description: Identifier of the identity. ,
Required: True ,
}
string ,
}
,
accessToken:
{
Description: An access token. ,
Required: False ,
}
{
token:
{
Description: The access token issued for the identity. ,
Required: True ,
}
string ,
expiresOn:
{
Description: The expiry time of the token. ,
Format: date-time ,
Required: True ,
}
string ,
}
,
}
TeamsExtensionAssignment_Get (new)
Description :  Get Teams Phone access assignment by object id.
Reference :  Link ¶

⚼ Request

GET:  /access/teamsExtension/tenants/{tenantId}/assignments/{objectId}
{
tenantId:
{
Description: Tenant Id we want to get the assignment for. ,
Required: True ,
}
string ,
objectId:
{
Description: Object Id we want to get the assignment for. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
objectId:
{
Required: True ,
}
string ,
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Description: The type of principal the assignment is for. ,
Enum:
{
resourceAccount: No description available. ,
user: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: False ,
}
[
string ,
]
,
}
TeamsExtensionAssignment_Upsert (new)
Description :  Creates or replaces a Teams Phone access assignment.
Reference :  Link ¶

⚼ Request

PUT:  /access/teamsExtension/tenants/{tenantId}/assignments/{objectId}
{
tenantId:
{
Description: Tenant Id we want to update the assignment for. ,
Required: True ,
}
string ,
objectId:
{
Description: Object Id we want to update the assignment for. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
body:
{
Description: Values we want to set. ,
Required: True ,
}
{
principalType:
{
Description: The type of principal the assignment is for. ,
Enum:
{
resourceAccount: No description available. ,
user: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: False ,
}
[
string ,
]
,
}
,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
objectId:
{
Required: True ,
}
string ,
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Description: The type of principal the assignment is for. ,
Enum:
{
resourceAccount: No description available. ,
user: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: False ,
}
[
string ,
]
,
}

⚐ Response (201)

{
objectId:
{
Required: True ,
}
string ,
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Description: The type of principal the assignment is for. ,
Enum:
{
resourceAccount: No description available. ,
user: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: False ,
}
[
string ,
]
,
}
TeamsExtensionAssignment_Delete (new)
Description :  Removes a Teams Phone access assignment.
Reference :  Link ¶

⚼ Request

DELETE:  /access/teamsExtension/tenants/{tenantId}/assignments/{objectId}
{
tenantId:
{
Description: Tenant Id we want to remove the assignment for. ,
Required: True ,
}
string ,
objectId:
{
Description: Object Id we want to remove the assignment for. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (204)

{}
EntraIdToken_Exchange (new)
Description :  Exchanges an Entra ID token for an ACS user access token.
Reference :  Link ¶

⚼ Request

POST:  /access/entra/:exchangeAccessToken
{
body:
{
Description: Request payload for the token exchange. ,
Required: True ,
}
object ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
identity:
{
Description: A communication identity. ,
Required: True ,
}
{
customId:
{
Description: The custom Id if one has been associated with the identity. ,
Required: False ,
}
string ,
lastTokenIssuedAt:
{
Description: Last time a token has been issued for the identity. ,
Format: date-time ,
Required: False ,
}
string ,
id:
{
Description: Identifier of the identity. ,
Required: True ,
}
string ,
}
,
accessToken:
{
Description: An access token. ,
Required: False ,
}
{
token:
{
Description: The access token issued for the identity. ,
Required: True ,
}
string ,
expiresOn:
{
Description: The expiry time of the token. ,
Format: date-time ,
Required: True ,
}
string ,
}
,
}
EntraIdAssignments_Update (new)
Description :  Updates Entra access assignments in bulk.
Reference :  Link ¶

⚼ Request

PATCH:  /access/entra/assignments
{
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
body:
{
Description: Set of assignments to be added, updated or removed. ,
Required: True ,
}
object ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
value:
{
Required: True ,
}
[
{
objectId:
{
Required: True ,
}
string ,
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Enum:
{
user: No description available. ,
group: No description available. ,
tenant: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: True ,
}
[
string ,
]
,
}
,
]
,
nextLink:
{
Required: False ,
}
string ,
}

⚐ Response (204)

{}
EntraIdAssignments_List (new)
Description :  Lists Entra access assignments.
Reference :  Link ¶

⚼ Request

GET:  /access/entra/assignments
{
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
value:
{
Required: True ,
}
[
{
objectId:
{
Required: True ,
}
string ,
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Enum:
{
user: No description available. ,
group: No description available. ,
tenant: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: True ,
}
[
string ,
]
,
}
,
]
,
nextLink:
{
Required: False ,
}
string ,
}
EntraIdAssignment_Get (new)
Description :  Get Entra access assignment by object id.
Reference :  Link ¶

⚼ Request

GET:  /access/entra/assignments/{objectId}
{
objectId:
{
Description: objectId we want to get the assignment for. AcsResourceId is taken from authentication. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
objectId:
{
Required: True ,
}
string ,
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Enum:
{
user: No description available. ,
group: No description available. ,
tenant: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: True ,
}
[
string ,
]
,
}
EntraIdAssignment_Upsert (new)
Description :  Creates or replaces an Entra access assignment.
Reference :  Link ¶

⚼ Request

PUT:  /access/entra/assignments/{objectId}
{
objectId:
{
Description: objectId we want to update the assignment for. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
body:
{
Description: Values we want to set. ,
Required: True ,
}
{
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Enum:
{
user: No description available. ,
group: No description available. ,
tenant: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: True ,
}
[
string ,
]
,
}
,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
objectId:
{
Required: True ,
}
string ,
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Enum:
{
user: No description available. ,
group: No description available. ,
tenant: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: True ,
}
[
string ,
]
,
}

⚐ Response (201)

{
objectId:
{
Required: True ,
}
string ,
tenantId:
{
Required: True ,
}
string ,
principalType:
{
Enum:
{
user: No description available. ,
group: No description available. ,
tenant: No description available. ,
}
,
Required: True ,
}
enum ,
clientIds:
{
Required: True ,
}
[
string ,
]
,
}
EntraIdAssignment_Delete (new)
Description :  Removes an Entra access assignment.
Reference :  Link ¶

⚼ Request

DELETE:  /access/entra/assignments/{objectId}
{
objectId:
{
Description: objectId we want to remove the assignment for. AcsResourceId is taken from authentication. ,
Required: True ,
}
string ,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (204)

{}