Tokens and access
For the HERAIOT web app, open app.heraiot.com .
Device access tokens
An API device has an access token used to authenticate its readings. Find it on the device overview, alongside the Copy API URL action.
- Send it as
Authorization: Bearer <token>. - One token belongs to one device. Do not share a token across devices — you lose the ability to revoke access for a single unit.
- Store it in the device’s secure configuration or an environment variable, never in source control.
A device token authenticates a device, not a person. Anyone holding it can submit readings as that device. Treat it like a password and rotate it if it may have been exposed.
The token is checked together with the device’s connection type: it is only accepted for devices configured as API devices.
MCP OAuth tokens
For AI assistant connections, use HERAIOT OAuth instead of a device token or MQTT password. The MCP guide explains sign-in, scoped endpoints, token refresh, and how account and tenant permissions apply.
MQTT credentials
MQTT devices authenticate to the broker with the credentials configured for that broker and device, not with the device API token. The two are separate and are not interchangeable.
See MQTT connections.
Tenants
A tenant is the workspace that owns your devices, entities, dashboards and users. Data does not cross tenants.
If a device or dashboard you expect is missing, confirm you are working in the intended tenant before investigating anything else. This is the most common explanation for a record that “disappeared”.
Roles and permissions
What you can see and do depends on your role and on your workspace permissions. Navigation items are hidden when your role does not grant access to them, so a missing menu entry is usually a permissions matter rather than a fault.
| If you cannot… | Ask your administrator to check |
|---|---|
| See a page in the sidebar | Your role |
| Edit a device or entity | Your permissions on that resource |
| See another team’s data | Tenant membership |
| Use a feature at all | The workspace subscription plan |
Some capabilities are tied to the workspace’s subscription plan rather than to your individual role.
User sessions
The web app uses a short-lived access token and renews it with a rotating refresh token. If renewal is rejected—for example after logout, password reset, an MFA change, expiry, or reuse of an old refresh token—the app clears the session and returns you to sign-in. A temporary network or server error keeps the session information and offers a retry rather than immediately signing you out.
Changing tenant creates a replacement token pair scoped to the selected workspace. Keep only one active login per user when possible: the current session store supports one refresh token per account, so signing in again can replace the prior browser’s ability to renew.
See Multi-factor authentication for the second sign-in step and recovery codes.
Shared dashboards
A shared dashboard link lets someone view a dashboard without signing in to the workspace. A password can be required for access.
Without a password, anyone with the link can view the dashboard. Set one before sharing anything sensitive, and treat the link itself as a credential.
Reporting a concern
If you believe a token or shared link has been exposed, rotate it and contact support. When sending logs or screenshots for any support request, remove tokens, passwords and access URLs first — see getting help.