1KEY Developers
Get started

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
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
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
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.