Share via

Communication Identity - Exchange Teams User Access Token

Service:
Communication
API Version:
2025-06-30

Exchange an Entra ID access token of a Teams user for a new Communication Identity access token with a matching expiration time.

POST {endpoint}/teamsUser/:exchangeAccessToken?api-version=2025-06-30

URI Parameters

Name In Required Type Description
endpoint
 path True

string (url)

The communication resource, for example https://my-resource.communication.azure.com
api-version
 query True

string

Version of API to invoke.

Request Body

Name Required Type Description
appId True

string

Client ID of an Entra ID application to be verified against the appid claim in the Entra ID access token.
token True

string

Entra ID access token of a Teams User to acquire a new Communication Identity access token.
userId True

string

Object ID of an Entra ID user (Teams User) to be verified against the oid claim in the Entra ID access token.

Responses

Name Type Description
200 OK

CommunicationIdentityAccessToken

Success
Other Status Codes

CommunicationErrorResponse

Error

Examples

Exchange a Teams user access token

Sample request

POST https://my-resource.communication.azure.com/teamsUser/:exchangeAccessToken?api-version=2025-06-30

{
  "token": "AzureActiveDirectoryAccessTokenOfATeamsUser",
  "appId": "2c3e1e83-8fd7-4615-ad2b-b8c1229845ac",
  "userId": "32c0a5db-05ec-78ea-51ab-3f06b329397e"
}

Sample response

Status code:
200 
{
  "token": "CommunicationIdentityAccessToken",
  "expiresOn": "2025-07-10T21:39:39.3244584+00:00"
}

Definitions

Name Description
CommunicationError

The Communication Services error.
CommunicationErrorResponse

The Communication Services error.
CommunicationIdentityAccessToken

An access token.
TeamsUserExchangeTokenRequest

A request to create or update a Teams Phone assignment.

CommunicationError

Object

The Communication Services error.

Name Type Description
code

string

The error code.
details

CommunicationError[]

Further details about specific errors that led to this error.
innererror

CommunicationError

The inner error if any.
message

string

The error message.
target

string

The error target.

CommunicationErrorResponse

Object

The Communication Services error.

Name Type Description
error

CommunicationError

The Communication Services error.

CommunicationIdentityAccessToken

Object

An access token.

Name Type Description
expiresOn

string (date-time)

The expiry time of the token.
token

string

The access token issued for the identity.

TeamsUserExchangeTokenRequest

Object

A request to create or update a Teams Phone assignment.

Name Type Description
appId

string

Client ID of an Entra ID application to be verified against the appid claim in the Entra ID access token.
token

string

Entra ID access token of a Teams User to acquire a new Communication Identity access token.
userId

string

Object ID of an Entra ID user (Teams User) to be verified against the oid claim in the Entra ID access token.