API Keys

View Api Keys in the API reference

API keys (Personal Access Tokens) let third parties use the OpenApp API programmatically without browser-based login.

Creating an API key

1. Log in to the dashboard and select an organization.
2. Go to Resources → API Keys.
3. Click Create API key, enter a name and expiration date.
4. Copy the token immediately—it is shown only once.

You need the api_keys:create role in the organization to create keys. See Roles.

Using an API key

Send the token in the X-API-Key header (when behind Oathkeeper) or Authorization: Bearer <token> (direct backend):

# With Oathkeeper (production)
curl -H "X-API-Key: YOUR_TOKEN" https://openapp.example.com/api/v1/devices

# Direct to backend (development)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/api/v1/devices

Token format

Tokens follow: {base_url}_openapp_{secret}

• base_url: The API base URL (e.g. https://openapp.example.com). Must match OPENAPP_API_BASE_URL on the server.
• secret: A random, URL-safe Base64 string.

The full token is shown once at creation. Store it securely.

Scoping (least privilege)

By default, an API key inherits all of your roles in the organization. For least-privilege access, you can scope a key to:

• Scoped roles: Only specific roles (e.g. entities:set_state).
• Scoped entity IDs: Only specific entities (e.g. one door).

When scoped, the key can only perform actions allowed by those roles on those entities.

Expiration

Each key has a required expires_at date. Expired keys are rejected. Create new keys before existing ones expire.

Lifecycle: Revoke vs Delete

API keys follow a two-stage deactivation model: revoke first, delete (optional) later.

States

1. Active – Key can authenticate API requests.
2. Revoked – Key is disabled; any request using it returns 401. The key remains in the database with a revoked_at timestamp.
3. Deleted – Key is permanently removed from the database. Only revoked keys can be deleted.

Revoke

When to use: You suspect a key was exposed, the key is no longer needed, or an employee/service no longer requires access.

Effect: The key stops working immediately. The row stays in the database so you can see when it was revoked. You can restore it later (if not expired) or delete it.

How: Dashboard (Resources → API Keys → Revoke) or DELETE /api/v1/api-keys/{id}.

Rationale: Revocation is quick and reversible. If a revoke was a false alarm (e.g. suspected leak that turned out safe), you can restore the key instead of creating a new one.

Restore

When to use: A key was revoked by mistake, or you want to re-enable it (e.g. contractor returning, temporary suspension ended).

Effect: Clears revoked_at; the key works again for API requests.

How: Dashboard (Resources → API Keys → Restore on a revoked key) or POST /api/v1/api-keys/{id}/restore. Returns 409 if the key is not revoked or is expired.

Rationale: Without restore, revoke is one-way and effectively equivalent to delete. Restore makes revoke useful for temporary or reversible disabling.

Delete (purge)

When to use: You want to remove revoked keys from the database (e.g. cleanup, privacy, or storage reduction).

Effect: The key row is permanently removed. This cannot be undone.

How: Dashboard (Resources → API Keys → Delete on a revoked key) or DELETE /api/v1/api-keys/{id}/purge. Returns 409 if the key is not revoked.

Rationale: Revoked keys may still contain metadata (name, expiry, scopes). Deleting them removes this data. Revocation must happen first to avoid accidentally deleting keys that are still in use.

Summary

Action	When to use	Reversible?
Revoke	Key compromised, no longer needed, temp suspension	Yes – use Restore to re-enable
Restore	Undo revoke (false alarm, temp suspension ended)	N/A – key is active again
Delete	Remove revoked key from database	No – row is gone

Typical flow: Create → use → Revoke (when no longer needed) → Restore (if needed) or Delete (for cleanup).

API reference

• Create: POST /api/v1/api-keys
• List: GET /api/v1/api-keys – returns active and revoked keys
• Revoke: DELETE /api/v1/api-keys/{id} – disables the key
• Restore: POST /api/v1/api-keys/{id}/restore – re-enables a revoked key (returns 409 if key is not revoked or is expired)
• Delete (purge): DELETE /api/v1/api-keys/{id}/purge – permanently removes a revoked key (returns 409 if key is not revoked)

Security

• Never commit tokens to source control.
• Rotate keys regularly.
• Use scoped keys when possible.
• Revoke keys that may have been exposed.