API Keys

API keys provide programmatic access to the Outcron API without requiring a user login. Each key is scoped to a single organization and carries its own set of permission tags.

Key Format

API keys use the outk_ prefix for easy identification:

outk_a1b2c3d4e5f6...
    

The full key is only shown once at creation time. After that, only the prefix is visible.

Creating an API Key

When creating a key, you specify:

• Name — a human-readable label to identify the key's purpose.
• Permissions — which permission tags the key carries (from the same catalog used by roles).
• Expiration — an optional expiration date. Expired keys are rejected automatically.

Permission Scoping

API keys use the same permission tag system as roles. A key can only access resources allowed by its permission tags. This means you can create narrowly-scoped keys — for example, a key with only executions:read for a monitoring dashboard.

Omitted or empty permissions deny org-member routes. API keys cannot access support ticket routes, platform-admin routes, or org-admin-only actions even when the key has every org permission.

Usage Tracking

Each API key tracks:

• Last used at — when the key was last used to authenticate a request.
• Last used IP — the IP address of the last request.
• Last used user agent — the User-Agent header of the last request.
• Use count — total number of authenticated requests.

Rotating an API Key

Rotation issues a new secret value for an existing key. The key's ID, name, permissions, and usage history are preserved — only the secret changes.

To rotate, open the API Keys page and click the rotate action on the row for the key you want to roll. The dialog asks for a grace period — how long the previous secret should remain valid so callers can migrate without downtime.

• Specify the grace period as a Go-style duration such as 1h, 24h, or 168h. The maximum is 720h.
• Use 0s to revoke the old secret immediately, with no overlap.
• Once the grace window expires, requests using the old secret are rejected with the same response as an unknown key.

The new secret is shown once after rotation — copy it immediately. The rotation response also exposes previous_key_prefix and previous_expires_at so callers can confirm which older secret is still accepted and when it stops working.

Security

• New and rotated keys are stored using a fast one-way SHA-256 digest of the full secret (sha256:-prefixed). Legacy keys (and in-grace previous secrets) remain bcrypt-hashed and are accepted transparently during verification. The plaintext key cannot be retrieved after creation.
• Revoke a key immediately if compromised. Revocation takes effect on the next request.

API Authentication

Include the key in the Authorization header:

Authorization: Bearer outk_a1b2c3d4e5f6...
    

The API responds with 401 Unauthorized if the key is invalid, expired, or revoked.