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
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. |
| A legacy Infuse IoT flow rejects an IAM API key | Use the legacy admin key from Infuse IoT > API Access until that integration supports IAM-issued credentials. |
| 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.