Troubleshooting Auth
Authentication failures mean the caller is not recognised. Authorization failures mean the caller is recognised but does not have permission for the requested action.
Authentication Checks
Check the credential first:
- The API key uses the complete
ik_<keyId>.<keySecret>value shown at issuance. - The key has not expired or been revoked.
- A personal key belongs to a current member of the active organisation.
- A service-account key belongs to an Active, unexpired service account.
- The organisation is the one that owns the user or service account.
If you are using token exchange, call:
POST /iam/auth/token
Set audience to infuse-iot for the Infuse-IoT Cloud API, or omit it for Infuse Platform APIs.
Then send the returned token as:
Authorization: Bearer <accessToken>
If you are using direct API-key auth, send:
Authorization: ApiKey ik_<keyId>.<keySecret>
Direct API-key auth also requires the organisation setting that allows it and an endpoint that supports it. Otherwise, exchange the key for a bearer token.
Authorization Checks
If authentication succeeds but the API call is denied, check the owning identity's access:
- The user or service account has an applicable role or direct grant.
- The assigned role supports that principal type.
- The assignment belongs to the correct organisation.
- The role or grant includes the permission required for the action.
- Any resource scope, start time, expiry, or condition matches the request.
Open the member or service account and use its Access view:
- Effective permissions is the current authorization result and names why each permission is granted.
- Additional roles shows roles assigned directly to the identity.
- Group-inherited roles shows access resolved from current group membership.
- Direct grants shows one-off permissions granted without a role.
An expired, scheduled, incompatible, or condition-limited assignment can appear under its source section without producing an effective permission.
Common Fixes
| Symptom | Check |
|---|---|
| Token exchange fails | Confirm the key value is complete, the credential is current, and its owning user or service account is eligible to authenticate. |
The Infuse-IoT Cloud API returns 401 for an IAM token | Exchange the key with "audience": "infuse-iot". Platform-audience tokens, Portal sessions, and developer tokens are not accepted by the IoT API. |
A Platform API returns 401 for an IAM token | Exchange the key with the default infuse-platform audience. Infuse IoT tokens are not accepted by Platform APIs. |
| An IoT call is denied despite a device- or board-limited grant | The Infuse-IoT Cloud API does not yet support resource-limited IoT grants. Grant the IoT permission organisation-wide. |
| An IoT call targets the wrong organisation | Use the organisation ID of the organisation that owns the API key. Keys are bound to one organisation. |
| An older tool only accepts a legacy Infuse IoT admin key | Legacy keys are deprecated and being retired. Update the tool to exchange an IAM API key for an infuse-iot token. |
| Direct API-key request fails | Confirm direct API-key auth is enabled for the organisation and supported by the endpoint, or exchange the key for a bearer token. |
| API call returns forbidden | Review the owner's Effective permissions and confirm the required permission, scope, and conditions. |
| A role is unavailable | Confirm the role supports User or Service account, as appropriate. |
| Member cannot access a workflow | Confirm the member is in the current organisation and review their membership level, additional roles, groups, and direct grants. |
| A group member did not inherit a role | Confirm the role supports that identity type, the membership change was saved, and the role is still assigned to the group. |
| A service-account key cannot authenticate | Confirm the account is active and neither the account nor key has expired. |
| An assignment is visible but access is denied | Check Effective permissions for an unmet condition, future or expired lifetime, or resource-scope mismatch. |
Do not call APIs with IAM credentials from browser code, mobile apps, device firmware, public repositories, or customer-visible examples.