Authentication
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, and set their time zone and location |
hubs:read |
List hubs, read their details and connection status; list devices, and read their settings, lock users, setup checks and SmartStart codes |
hubs:write |
Add hubs to sites, move, rename and remove them; add, remove, name and place devices; change settings; manage lock users and credentials and SmartStart codes; run setup actions, replace a device and reset the network |
hubs:command |
Send commands and read their outcome, and run a device's setup test |
intercoms:read |
List intercoms, read their details, connection status, uptime, directory and masked codes |
intercoms:write |
Add intercoms to sites, move, rename and remove them, and reset their cloud link |
intercoms:command |
Open an intercom's door |
automations:read |
Read automations, schedules, traces, templates, deployments and calendars |
automations:write |
Save, enable, disable, validate and delete automations, schedules, templates and calendars, and deploy templates |
automations:run |
Run and test automations, and fire remote triggers |
automations:unlock |
Save or deploy an automation or schedule that unlocks a lock or opens a garage door |
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 |
organization:write |
Rename the organization |
api_keys:read |
List API keys (never their secrets) and their usage |
api_keys:write |
Create keys with at most this key's scopes, and rotate and revoke keys |
A request outside the key's scopes gets 403 insufficient_scope, naming the scope it needs.
GET /organization is the one read that needs no scope: any key reads its organization's ID and name, and the role the key acts with.
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 them with
POST /api-keys/{id}/rotate.
Managing keys with the API
A key with api_keys:write creates keys:
curl -X POST https://api.1keyplatform.dev/v1/api-keys \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "reporting", "scopes": ["hubs:read", "events:read"]}'
The answer's token is the only copy of the new key. A key can't create a key with scopes it doesn't have (403 insufficient_scope), and the new key acts as the creating key's creator. GET /api-keys lists keys without their secrets (status=active or revoked), each with created_by, the person it acts as, and parent_key_id, the key that created it. DELETE /api-keys/{id} revokes one.
A key created with a key depends on it: revoking a key also revokes every key it created, and theirs in turn.
Rotating keys
POST /api-keys/{id}/rotate replaces a key with a new one and returns it with its token, shown once. The new key has the old key's name, scopes and creator, and rotated_from_id set to the old key. It takes the old key's place in the tree: its parent is the old key's parent, so retiring the old key doesn't touch it.
A key rotates itself, so a server holding one key can replace it. Otherwise the rules for revoking apply: owners and admins rotate any key, members only keys they created. It needs api_keys:write.
curl -X POST https://api.1keyplatform.dev/v1/api-keys/$KEY_ID/rotate \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"grace_seconds": 3600}'
grace_seconds (0 to 86400, default 0) is how long the old key keeps working. With 0 it is revoked in the same request. Otherwise its revoke_at is set, and it stops working at that time; it is then listed with status=revoked, with revoked_at set. Deploy the new key within the window.
Keys the old key created stay its children: they stop working when it does, not with the new key. Rotate or recreate them with the new key first.
A revoked key, or one past its revoke_at, can't be rotated (409 conflict). Every rotation emails the organization's owners and admins: which key, who rotated it (a person, or the key itself), and when the old key stops working.
Usage and the request log
Owners and admins read every key's usage and requests; members those of keys they created. Both need api_keys:read.
GET /usage returns requests, errors and rate-limited requests per key per hour, from since (default 24 hours ago), kept 30 days. With granularity=day it counts per UTC day, by default over the last 14 days. The API keys page downloads the hourly counts as CSV.
GET /requests returns requests from the last 30 minutes, newest first, with sensitive values removed. Filter by api_key_id, status (2xx, 4xx or 5xx) or request_id, and page back with before set to the last entry's id:
curl "https://api.1keyplatform.dev/v1/requests?status=4xx&limit=20" \ -H "Authorization: Bearer $ONEKEY_API_KEY"
GET /requests/stream sends each request as it is logged, as Server-Sent Events with the same filters. Each message's id is the entry's id; reconnect with Last-Event-ID to continue after it. A stream counts toward the open stream limits.