API key security from creation to revocation

Own Auth treats an API key as a persistent credential record with a one-time secret, not as a string copied into an environment variable and forgotten. The record carries an owner, name, visible prefix, scopes, status, creation time, optional expiry, and last-used time. That metadata makes one integration independently identifiable and revocable without exposing the credential that authenticates it.

Creation and storage

auth.createApiKey creates either a user-owned key or an organisation-owned key. Organisation key creation requires the actor to have the built-in manage_api_keys permission. The method returns rawKey with the API key metadata, writes an api_key.created audit event, and applies Own Auth's key-creation rate limit. Only that creation response contains the complete credential. Later list operations expose metadata, including keyPrefix, without recovering the secret.

Own Auth formats each application key with a visible prefix and cryptographically random secret. It hashes the complete value with OWN_AUTH_TOKEN_PEPPER before storage. A database export therefore does not contain immediately usable keys, while the prefix still lets a management screen or audit event identify a record. Keep the pepper server-only and separate from the database. Rotating it invalidates sessions, auth tokens, codes, invitations, and API keys, so pepper replacement is an incident action that requires coordinated reauthentication.

Create a separate key for each production service, development environment, scheduled job, and customer integration. Sharing one key across workloads removes the ability to attribute traffic or revoke one compromised integration. Names should identify the workload and environment. Temporary jobs should receive an expiry at creation rather than depending on later cleanup.

Verification and authorization

Read the complete key from the Authorization: Bearer header on the backend and pass it to auth.verifyApiKey. Own Auth validates the format and stored hash, rejects expired or revoked records, updates safe usage metadata, and returns the associated API key plus its user or organisation context. Use the same public 401 response for malformed, unknown, and mismatched credentials. Do not include the submitted key in request snapshots, exception context, traces, or analytics.

• Accept keys only over HTTPS and only on server-controlled routes.
• Never accept a key in a query string, where proxies, histories, referrers, and access logs can retain it.
• Pass required scopes as the second argument to auth.verifyApiKey for each protected operation.
• Apply endpoint rate limits and resource authorization after verification.

Scopes describe product capabilities such as reports:read or webhooks:write. Own Auth can require those strings during verification, but the application defines their meaning. A verified organisation key with reports:read still needs a query constrained to its owning organisation. It must not read another tenant's report because a caller supplied a different organisation ID. Treat an empty scope set according to an explicit product policy; an omitted array must not silently become full access.

Rotation and revocation

Rotate a key by creating a second record, updating the integration, confirming traffic on the replacement prefix, and then revoking the original. Do not overwrite the old secret in place. Separate records preserve attribution during the overlap and leave the old key independently revocable. The overlap should be short and observable, with an explicit rollback point before revocation.

Revocation must affect the next call to auth.verifyApiKey. Revoke immediately after a key appears in source control or telemetry, when an integration is retired, or when its owner loses the authority from which the key was issued. Expiry limits a temporary key's useful lifetime but does not replace revocation after confirmed exposure.

Safe operational evidence

An API key management surface needs the record ID, name, owner, prefix, scopes, creation time, expiry, last-used time, and status. Those fields answer which integration is active without retrieving the key. Last-used time is a diagnostic signal, not proof of safety: a low-volume stolen credential can remain valid between requests.

Record creation and revocation as audit events, and correlate request activity by record ID or visible prefix. Never store the raw key in an audit event. Organisation revocation must require the same ownership or manage_api_keys authorization used by Own Auth's key management methods. This keeps investigation and response attached to the credential record while the bearer value remains absent from every operational system except the integration that uses it.