The Identity API is the second call in the SDK workflow. After Discovery returns the base URL, call the Identity API to retrieve your device connection details including MQTT broker, topics, and authentication parameters.
After the Discovery API returns the base URL (bu field), append the Identity endpoint to fetch device-specific connection details. The Identity API returns everything your SDK needs to connect: MQTT broker hostname, port, topics for publishing (D2C) and subscribing (C2D), and device authentication info.
| Parameter | Description |
|---|---|
| Base URL | The bu value returned from the Discovery API |
| Endpoint | /api/v2.1/agent/sync |
| Method | GET |
| Headers | Device Unique ID and authentication token |
Example:
GET https://{BASE_URL}/api/v2.1/agent/sync?uid={DEVICE_UNIQUE_ID}
The Identity API returns a comprehensive JSON response with these key fields:
p.h (Host): MQTT broker hostname to connect to.
p.p (Port): MQTT broker port (typically 8883 for TLS).
p.pub (Publish Topic): MQTT topic for sending D2C telemetry messages.
p.sub (Subscribe Topic): MQTT topic for receiving C2D commands.
d.at (Auth Type): Authentication type code (1=Key, 2=X.509, etc.).
d.ct (Connection Type): Device connection type identifier.
att (Attributes): Array of template attributes the device should report.
set (Settings): Device twin/shadow desired properties from the cloud.
On successful call, you will receive the following JSON response. Use the protocol details (p) to establish your MQTT connection.
Cache the Identity response. Only call it again if you need to reconnect after an extended disconnection or if a Template Change C2D message is received indicating configuration updates.