# Identity.Create Request

A user can use the identity.create request to create an indirectly connected device identity only. It is not possible to create the identity for a directly connected device via this request. The request will alert the platform to create a device identity via the principal manager. identity.create action message is sent to the platform by a connected device (i.e. Edge) via IoTHub.

Before a user can send this message successfully, the identity of the directly connected device (Edge) must have been created by tenant admin during bootstrap process and the (Principal Manager) parent identity must exist and must be connected via the directly connected device (Edge).

# Idempotency

This request is idempotent, meaning that sending several identical requests will result in the identity being successfully created in PM. One of the two following outcomes will occur due to this design:

if an identity does not exist yet, it will be created
if an identity already exists (determined via identity in the context of a parent), creation will be ignored and result will be considered successful

# Event Properties

# Unique Message Headers

Property	Mandatory	Description
parent	Optional	a parent of this new identity, as a relative path. This identity must already exist and must be connected via this directly connected device. If absent, a directly connected device will become a parent of this new identity

# Message Body

Property	Mandatory	Data Type	Description
identity	Required	string	Identity must be unique within the parent

# Message Format

identity.create action message has following format when it is received and ready for processing. Only showing data relevant for message processing.

{
    "action": "identity.create",
    "msgType": "action",
    "version": 2,
    "ack": "<ack>",
    "correlationId": "<GUID>",
    "target": "<connected device path>",
    "parent": "<relative path>",
    "body": {
        "identity": "<identity value>"
    }
}

# Validation Rules

DCS validates all message properties, the message body, and message body property identity as specified in the v2 Device API summary page. The message body is then passed to Region API POST /devices or PUT /devices/{deviceId} endpoint where remaining validation is performed.

# Example Message Format

{
    "iothub-connection-device-id": "<device id>",
    "action": "identity.create",
    "msgType": "action",
    "version": 2,
    "ack": "all",
    "correlationId": "a7397ccc-ddb7-4839-ab35-add28724cdb9",
    "parent": "ModuleIdentity",
    "body": {
        "identity": "IdentityValue"
    }
}

# Expected Acknowledgment Responses

# Positive Acknowledgement

{
    "properties": {
        "msgType": "ack",
        "action": "identity.create",
        "correlationId": "<correlation id>",
        "version": 2,
        "target": "<some_target>"
    },
    "body": {
        "success": true,
        "code": "<error code>",
        "detail": "<error detail>",
        "parent": "<parent from the identity.create message>",
        "identity": "<identity from the identity.create message>"
    }

}

# Negative Acknowledgement

{
    "properties": {
        "msgType": "ack",
        "action": "identity.create",
        "correlationId": "<correlation id>",
        "version": 2,
        "target": "<some_target>",
    },
    "body": {
        "success": false,
        "code": "<error code>",
        "detail": "<error detail>",
    }
}

# Functionality

The device principal for the requested identity is created via the principle manager and connected to a parent. A notification and an acknowledgement are two different pieces of information. DCS will never send back a 'request-response' notification message. Any platform events generated by the IM service related to this request are ignored by the DCS. If requested, an acknowledgement c2d message can be sent back to the directly connected device where it can also be propagated further if needed (based on target). The target is determined based on the message property listed above.

# Error handling

If a response can be delivered back to device, acknowledgments are sent back to device, if the acknowledgements have been requested in the solution configuration. More details can be found here: Acknowledgement Handling

← Platform Error Responses Identity.Update (V2) →