# Troubleshooting Auth

> Diagnose IAM authentication and authorization failures.

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:

```http
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:

```http
Authorization: Bearer <accessToken>
```

If you are using direct API-key auth, send:

```http
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

<table>
<thead>
  <tr>
    <th>
      Symptom
    </th>
    
    <th>
      Check
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Token exchange fails
    </td>
    
    <td>
      Confirm the key value is complete, the credential is current, and its owning user or service account is eligible to authenticate.
    </td>
  </tr>
  
  <tr>
    <td>
      The Infuse-IoT Cloud API returns <code>
        401
      </code>
      
       for an IAM token
    </td>
    
    <td>
      Exchange the key with <code>
        "audience": "infuse-iot"
      </code>
      
      . Platform-audience tokens, Portal sessions, and developer tokens are not accepted by the IoT API.
    </td>
  </tr>
  
  <tr>
    <td>
      A Platform API returns <code>
        401
      </code>
      
       for an IAM token
    </td>
    
    <td>
      Exchange the key with the default <code>
        infuse-platform
      </code>
      
       audience. Infuse IoT tokens are not accepted by Platform APIs.
    </td>
  </tr>
  
  <tr>
    <td>
      An IoT call is denied despite a device- or board-limited grant
    </td>
    
    <td>
      The Infuse-IoT Cloud API does not yet support resource-limited IoT grants. Grant the IoT permission organisation-wide.
    </td>
  </tr>
  
  <tr>
    <td>
      An IoT call targets the wrong organisation
    </td>
    
    <td>
      Use the organisation ID of the organisation that owns the API key. Keys are bound to one organisation.
    </td>
  </tr>
  
  <tr>
    <td>
      An older tool only accepts a legacy Infuse IoT admin key
    </td>
    
    <td>
      Legacy keys are deprecated and being retired. Update the tool to exchange an IAM API key for an <code>
        infuse-iot
      </code>
      
       token.
    </td>
  </tr>
  
  <tr>
    <td>
      Direct API-key request fails
    </td>
    
    <td>
      Confirm direct API-key auth is enabled for the organisation and supported by the endpoint, or exchange the key for a bearer token.
    </td>
  </tr>
  
  <tr>
    <td>
      API call returns forbidden
    </td>
    
    <td>
      Review the owner's <strong>
        Effective permissions
      </strong>
      
       and confirm the required permission, scope, and conditions.
    </td>
  </tr>
  
  <tr>
    <td>
      A role is unavailable
    </td>
    
    <td>
      Confirm the role supports <strong>
        User
      </strong>
      
       or <strong>
        Service account
      </strong>
      
      , as appropriate.
    </td>
  </tr>
  
  <tr>
    <td>
      Member cannot access a workflow
    </td>
    
    <td>
      Confirm the member is in the current organisation and review their membership level, additional roles, groups, and direct grants.
    </td>
  </tr>
  
  <tr>
    <td>
      A group member did not inherit a role
    </td>
    
    <td>
      Confirm the role supports that identity type, the membership change was saved, and the role is still assigned to the group.
    </td>
  </tr>
  
  <tr>
    <td>
      A service-account key cannot authenticate
    </td>
    
    <td>
      Confirm the account is active and neither the account nor key has expired.
    </td>
  </tr>
  
  <tr>
    <td>
      An assignment is visible but access is denied
    </td>
    
    <td>
      Check <strong>
        Effective permissions
      </strong>
      
       for an unmet condition, future or expired lifetime, or resource-scope mismatch.
    </td>
  </tr>
</tbody>
</table>

Do not call APIs with IAM credentials from browser code, mobile apps, device firmware, public repositories, or customer-visible examples.