The Discovery API is the first call your device makes to /IOTCONNECT™. It returns the base URL for the Identity service, allowing your SDK to locate the correct regional endpoint for all subsequent communication.
The Discovery API resolves your account’s regional endpoint. You call it once during SDK initialization with your company identifiers, and it returns the base URL you use for all Identity and Agent Sync calls.
You can find your Discovery URL in the /IOTCONNECT™ portal under Settings > Key Vault.
Call the discovery endpoint using your Company CPID and Environment:
| Parameter | Description |
|---|---|
| Base URL | From Key Vault in your /IOTCONNECT™ portal |
| Endpoint | /api/v2.1/dsdk/cpId/{COMPANY_CPID}/env/{ENVIRONMENT} |
| Method | GET |
Example request:
GET https://{DISCOVERY_URL}/api/v2.1/dsdk/cpId/YOUR_CPID/env/YOUR_ENV
Alternatively, call discovery using your Solution ID (SID):
| Parameter | Description |
|---|---|
| Base URL | From Key Vault in your /IOTCONNECT™ portal |
| Endpoint | /api/v2.1/dsdk/sid/{COMPANY_SID} |
| Method | GET |
Example request:
GET https://{DISCOVERY_URL}/api/v2.1/dsdk/sid/YOUR_SID
The Discovery API returns a JSON response with the following structure:
| Field | Type | Description |
|---|---|---|
d.ec |
Integer | Error code. 0 = success |
d.bu |
String | Base URL of the Identity service (use for next step) |
d.log:mqtt.hn |
String | MQTT broker hostname for optional device logging |
d.log:mqtt.un |
String | MQTT username for logging connection |
d.log:mqtt.pwd |
String | MQTT password for logging connection |
d.log:mqtt.topic |
String | MQTT topic for sending log messages |
d.pf |
String | Platform identifier (aws or az) |
status |
Integer | HTTP status code (200 = success) |
message |
String | Human-readable result message |
| Code | Message | Action |
|---|---|---|
| 0 | Success | Proceed to Identity API using the returned base URL |
| 1 | Invalid CPID | Verify CPID in Settings > Key Vault |
| 2 | Company not found | Check your account registration status |
| 3 | Subscription Expired | Renew your /IOTCONNECT™ subscription |
The Discovery URL and your CPID/Environment values are available in the /IOTCONNECT™ portal at
SETTINGS > KEY VAULT
Cache the base URL (bu) returned by this call. You only need to call Discovery once per device session unless the connection fails.
