Authentication
Every request carries an API key as a bearer token:
Authorization: Bearer 1key_live_4tj2q7xkn3mzd_…
Requests without a valid key get 401 unauthenticated.
API keys
Create keys on the API keys page. A key belongs to your organization, not to the person who created it, and reaches only your organization's hubs.
| Part | Example | Meaning |
|---|---|---|
| Prefix | 1key_live_ |
live in production, dev in development |
| Key ID | 4tj2q7xkn3mzd |
Shown in the portal; use it to tell keys apart in logs |
| Secret | the rest | Shown once, at creation |
The full key is shown once. 1key stores only a hash of it, so a lost key cannot be recovered: revoke it and create another.
Scopes
A key can do only what its scopes allow. Give each server the fewest scopes it needs.
| Scope | Allows |
|---|---|
sites:read |
List sites and read their details |
sites:write |
Create and rename sites |
hubs:read |
List hubs, read their details and connection status, list devices |
hubs:write |
Add hubs to sites, move and rename them; add, remove, name and place devices |
hubs:command |
Send commands and read their outcome |
events:read |
Read and stream events |
members:read |
List members and pending invitations |
members:write |
Invite people, revoke invitations, change admin and member roles, remove members |
A request outside the key's scopes gets 403 insufficient_scope, naming the scope it needs.
Keeping keys safe
- Keep keys in a secret manager or environment variable, never in source control or client-side code.
- Use one key per server or job, so revoking one does not break the others.
- Revoke a key from the API keys page as soon as you suspect it leaked. Requests with it fail immediately.
- Keys never expire on their own. Rotate by creating a new key, deploying it, then revoking the old one.