Create Twin Identity

This endpoint creates one or more Identities and attaches them to the given Twin.

Method	Path	Operation*
POST	/twins/{twin}/identities	create_twin_identity

*

In order for a user to perform the "create_twin_identity" operation, the "create_twin_identity" permission must be included in the list of allowed actions in the statement of the user's role.

Request

Parameter	Type	In	Type
{twin} required	string	path	Twin UUID.
identities	dictionary	body	Dictionary containing Identities with their parameters: - key: Identity name. String matching the regular expression(opens new window) ^[A-Za-z_][0-9A-Za-z_]{0,7}#[0-9A-Za-z_=+-]{1,128}$. - value: Identity parameters.

Identity parameters

Parameter	Type	In	Description
validity_ts optional *	timestamp, DEFAULT=null	body	Time at which the Identity expires. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). If not provided, the value is set to null and the Identity does not expire.
visibility optional *	string, DEFAULT=null	body	Visibility of the Identity. An Identity created in an account is visible to users belonging to that account. If the value of the "visibility" attribute is null, the Identity is private. Private Identities are only visible to users of the account that owns the Identity. If the value is not null, the Identity is public. Public Identities are visible to users of the account that owns the Identity and as well to users of other accounts if the visibility rule held in the "visibility" attribute evaluates to True.

*

The "visibility" and "validity_ts" parameters are optional and do not need to be included in the request body when creating Identities. If they are not included in the request body, their default values are used.

In our example we create two Identities. We attach them to the Twin with the Twin UUID "f63ce1df-4643-49b2-9d34-38f4b35b9c7a".

The first Identity is "RFID#ae144bdc-0f6d-4a00-4091-1a6d793aaaa":

• It expires on the 8th of March 2023 at 10:23:14 a.m. GMT ("validity_ts": 1678270994.000).
• It is a public Identity. Public Identities are visible to users of the account that owns the Identity and also to users of other accounts if the visibility rule of the Identity evaluates to True. In our example, the Identity is visible to users whose "profession" is either "accounting" or "sales" ("visibility": "USER.profession == 'accounting' or USER.profession == 'sales'").

The second Identity is "RFID#be144bdc-0f6d-4a00-4091-1a6d793cbbbb":

• It does not expire ("validity_ts": null).
• The Identity is private ("visibility": null). Private Identities are only visible to users of the account that owns the Identity.

Response

The response returns a list of Identities with their attributes.

Attribute	Type	Description
identities	dictionary	Dictionary containing Identities with their attributes: - key: Identity name. String matching the regular expression(opens new window) ^[A-Za-z_][0-9A-Za-z_]{0,7}#[0-9A-Za-z_=+-]{1,128}$. - value: Identity attributes.

Identity attributes

Attribute	Type	Description
visibility	string	Visibility of the Identity. An Identity created in an account is visible to users belonging to that account. If the value of the "visibility" attribute is null, the Identity is private. Private Identities are only visible to users of the account that owns the Identity. If the value is not null, the Identity is public. Public Identities are visible to users of the account that owns the Identity and as well to users of other accounts if the visibility rule held in the "visibility" attribute evaluates to True.
validity_ts	timestamp	Time at which the Identity expires. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). If the value is null, the Identity does not expire.
updated_ts	timestamp	Time at which the Identity was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
creation_certificate	dictionary	Certificate generated automatically by the system upon creation of the Identity. The creation certificate cannot be modified after it has been generated. Attribute Type Description identity string User-defined ID for the Identity. It must match the regular expression(opens new window) ^[A-Za-z_][0-9A-Za-z_]{0,7}#[0-9A-Za-z_=+-]{1,128}$. creator string Account UUID of the account creating the Identity. created_ts timestamp Time at which the Identity was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).

Response ('Identity already exists')

NOTE

If you try to create an Identity that already exists, you will receive the message "error": 'Identity already exists.'" for this particular Identity in the response. However, the response itself will return the 201 Created status code. Please see the below example for more details.

In the example below, we create two Identities - the Identity "RFID#ae14bdc-0f6d-a00-4091-1a6d793aaaa" ( it already exists in the account) and the Identity "RFID#ae14bdc-0f6d-a00-4091-1a6d793dddd" (it does not exist in the account yet).

The response returns the message "error": "Identity already exists." for the Identity "RFID#ae14bdc-0f6d-a00-4091-1a6d793aaaa" (the Identity that already exists in the account) and the details of the created Identity "RFID#ae14bdc-0f6d-a00-4091-1a6d793dddd". The status code of the response is 201 Created.

Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.

Status code	Message	Comment
201	Created	If an Identity that you are trying to create already exists, you will receive the error: "error": "Identity already exists." for this Identity in the response.