Communication Identity - Create

Reference

Service:: Communication

API Version:: 2023-10-01

Create a new identity, and optionally, an access token.

POST {endpoint}/identities?api-version=2023-10-01

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	The communication resource, for example https://my-resource.communication.azure.com
api-version	query	True	string	Version of API to invoke.

Request Body

Name	Type	Description
createTokenWithScopes	CommunicationIdentityTokenScope[]	Also create access token for the created identity.
expiresInMinutes	integer	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.

Responses

Name	Type	Description
201 Created	CommunicationIdentityAccessTokenResult	Created - Returns the created identity.
Other Status Codes	CommunicationErrorResponse	Error

Examples

Create an Identity and optionally an access token with custom expiration time within the [60-1440] minutes range. If expiration time is not specified, the default value of 1440 minutes (24 hours) will be used.

Sample Request

HTTP

POST https://my-resource.communication.azure.com/identities?api-version=2023-10-01

{
  "createTokenWithScopes": [
    "chat",
    "voip",
    "chat.join",
    "chat.join.limited",
    "voip.join"
  ],
  "expiresInMinutes": 60
}

Sample Response

Status code:: 201

{
  "identity": {
    "id": "8:acs:2dee53b4-368b-45b4-ab52-8493fb117652_00000005-14a2-493b-8a72-5a3a0d000081"
  },
  "accessToken": {
    "token": "token",
    "expiresOn": "2023-10-10T21:39:39.3244584+00:00"
  }
}

Definitions

Name	Description
CommunicationError	The Communication Services error.
CommunicationErrorResponse	The Communication Services error.
CommunicationIdentity	A communication identity.
CommunicationIdentityAccessToken	An access token.
CommunicationIdentityAccessTokenResult	A communication identity with access token.
CommunicationIdentityCreateRequest
CommunicationIdentityTokenScope	List of scopes for an access token.

CommunicationError

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

The Communication Services error.

Name	Type	Description
error	CommunicationError	The Communication Services error.

CommunicationIdentity

A communication identity.

Name	Type	Description
id	string	Identifier of the identity.

CommunicationIdentityAccessToken

An access token.

Name	Type	Description
expiresOn	string	The expiry time of the token.
token	string	The access token issued for the identity.

CommunicationIdentityAccessTokenResult

A communication identity with access token.

Name	Type	Description
accessToken	CommunicationIdentityAccessToken	An access token.
identity	CommunicationIdentity	A communication identity.

CommunicationIdentityCreateRequest

Name	Type	Default Value	Description
createTokenWithScopes	CommunicationIdentityTokenScope[]		Also create access token for the created identity.
expiresInMinutes	integer	1440	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.

CommunicationIdentityTokenScope

List of scopes for an access token.

Name	Type	Description
chat	string	Use this for full access to Chat APIs.
chat.join	string	Access to Chat APIs but without the authorization to create, delete or update chat threads.
chat.join.limited	string	A more limited version of chat.join that doesn't allow to add or remove participants. Use this scope when the token bearer is not fully trusted, for example in guest scenarios.
voip	string	Use this for full access to Calling APIs.
voip.join	string	Access to Calling APIs but without the authorization to start new calls.