Authentication & Security
The IoT.live API uses request-body authentication. Each API request includes the user credentials and organisational API license key directly inside the JSON request body.
This differs from APIs that use Bearer tokens or API keys in HTTP headers.
[IMAGE PLACEHOLDER: API authentication flow]
Authentication requirements
Before calling the API, you need:
- A valid IoT.live account
- API-enabled username and password credentials
- An organisational API license key
- Access to the correct API pod or environment
Documented API endpoints include:
Request method and headers
Unless otherwise stated, API calls use:
- HTTPS
- TLS 1.2 or higher
- HTTP POST
- JSON request bodies
Required header:
API credentials are submitted inside the request body, so all requests must be sent over HTTPS.
RequestAbstract
Most API requests include a shared authentication object called RequestAbstract.
This object contains the base authentication fields required by the API.
RequestAbstract fields
Field | Required | Description |
|---|---|---|
corrId | No | Optional correlation ID. Echoed back in the API response. |
username | Yes | API-enabled username. |
password | Yes | Password for the API-enabled user. |
licenseKey | Yes | Organisational API license key. |
Use corrId to trace requests through your own systems and match API responses back to the original request.
API license key
The organisational API license key can be retrieved from:
- The signup or onboarding email
- The Account Management section of the IoT.live portal
Typical portal flow:
- Open Account Management
- Edit the account details
- Copy the API key
[IMAGE PLACEHOLDER: Copy API key from Account Management]
Example authenticated request
Example request to retrieve connection inventory using listConnections:
Standard response object
Most API responses include a shared response structure.
Response fields
Field | Description |
|---|---|
result | API result status. |
responseMsg | Descriptive message. Usually null when successful. |
corrId | Correlation ID matching the original request. |
responseTime | Response timestamp in UTC milliseconds from Unix epoch. |
version | Responding API service version. |
Common authentication and access results
The API may return different result values depending on authentication, permissions, account status, or request processing.
Common values include:
Result | Meaning |
|---|---|
Success | Request completed successfully. |
Authentication_Failed | Username or password is incorrect. |
Not_Allowed | Credentials are valid, but the user or account is not authorised for the requested action. |
Password_Expired | The user password has expired. |
User_Locked | The user account is locked. |
Captcha_Required | Too many failed login attempts have triggered CAPTCHA enforcement. |
No_Contract | The account does not have a contract for the requested service. |
Contract_Expired | The contract for the requested service has expired. |
API user security
For production integrations, recommended security practices include:
- Use dedicated API-enabled users
- Restrict permissions to only what the integration needs
- Store credentials securely
- Avoid hardcoding passwords in scripts
- Rotate passwords according to organisational policy
- Separate production and test credentials where possible
API credentials may allow operational changes to live subscriptions. Treat them as sensitive secrets.
Password rotation
API-only users and UI/API users may behave differently.
In the source API documentation:
- API-only user passwords do not automatically rotate
- UI/API user passwords need to be periodically rotated in the portal
Confirm the correct user type before building long-running integrations.