Authentication
Every request to the API carries an API key as a bearer token. Keys are created and managed in the app, scoped to exactly what an integration needs, and shown in full only once.
Where to find it: Sidebar → Account settings → Integrations tab.
Creating a key
- Open Account settings and select the Integrations tab.
- Click Create API key.
- Give it a recognizable name (for example,
Acme BI export). This is how you will identify the key later. - Choose the scopes the integration needs. Grant only what it uses. See Scopes below.
- Optionally set an expiry date. Leave it empty for a key that never expires.
- Click Create.
The full key is shown once, immediately after creation, in the form iox_live_…. Copy it then and store it somewhere safe. ioX-Pulse keeps only a hashed version, so the secret cannot be shown again. If you lose it, revoke the key and create a new one.
Treat a key like a password. Anyone holding it can read your data within its scopes. Do not paste keys into chat tools, commit them to source control, or email them. Use a secrets manager or environment variable in your application.
Permission required: Partner Admin, or Sub-account Admin for keys scoped to a sub-account.
Using a key
Send the key in the Authorization header as a bearer token:
curl -H "Authorization: Bearer iox_live_your_key_here" \
https://portal.example.com/api/v1/me
The /me endpoint is a quick way to confirm a key works. It returns the tenancy and scopes the key resolves to.
Scopes
Scopes follow least privilege: a key can only do what its scopes allow. The read scopes, the downlinks:write scope, and the two member scopes below are active today. The remaining write scope and the webhook-management scope are reserved for upcoming features. Webhooks themselves are available now and are managed in the app. See Webhooks.
| Scope | Grants | Status |
|---|---|---|
devices:read | List and read devices and gateways. | Active |
telemetry:read | Read latest values and history. | Active |
profiles:read | Read device profiles and their field catalog. | Active |
telemetry:write | Push readings into ioX-Pulse. | Coming with the write API |
downlinks:write | Queue downlinks to a device, and execute multicast groups. | Active |
members:read | Validate a member login and list a sub-account's members. | Active |
members:manage | Add and remove sub-account members. | Active |
webhooks:manage | Manage webhook subscriptions through the API. | Reserved; webhooks are managed in the app today |
A key with no matching scope for an endpoint receives 403 insufficient_scope.
Member management (list, add, remove) requires a sub-account-scoped key (see below); a partner-scoped key receives 403 subaccount_key_required on those routes. Validating a member login works with either key flavor: a sub-account key checks its own sub-account, a partner key resolves the member's sub-account(s) across the partner. See Members for details.
Write endpoints also require that your plan includes API write access. A key that holds downlinks:write but is on a plan without write access receives 403 write_not_enabled.
What a key can see
A key is bound to the workspace it was created in:
- A partner key can read every device, gateway, and profile in your partner account, including those assigned to sub-accounts.
- A sub-account key is locked to a single sub-account and sees only that sub-account's devices and gateways.
A request can never reach another tenant's data. A resource that exists in a different partner or sub-account is reported as not found, the same as one that does not exist at all.
A key's binding is set when you create it: create a key at the partner level for a partner key, or while acting as a sub-account for a key bound to that sub-account. The Bound to column in the keys list shows which it is, labeling each key Partner or with the sub-account's name. The partner-level list shows every key in your partner; a sub-account's list shows only that sub-account's keys.
The member endpoints go one step further: they are available only to a sub-account key, and they always act on that key's own sub-account. There is no way to name another sub-account, so a member key can never touch anyone else's team.
Expiry and revocation
- Expiry is optional and set at creation. After the expiry date the key stops working.
- Revoke a key at any time from the Integrations tab. Revocation is immediate and cannot be undone. Any application using the key loses access on its next request, so rotate the application to a new key first.
Key creation and revocation are both recorded in your audit log.