Create and manage API keys

Gateway API keys are project credentials for calling Ethen’s Gateway rather than provider credentials used for BYOK. Manage them as revocable application secrets with clear ownership, environment, scope, and expiry metadata.

The key-management implementation is grounded, but the overall Gateway release posture can still be Beta or setup-required.

Treat every key as an independently managed project credential with a clear owner, environment, purpose, and retirement plan. Prefix and suffix metadata help identify the key without exposing it; last-used and expiry information help determine whether replacement or revocation is safe. Rotation should produce a short overlap in which both keys are valid, followed by evidence that clients have moved to the replacement. The old key can then be revoked without relying on a recoverable copy of either secret.

Create a key

A newly created key is project-scoped. The raw secret is returned once, while the service stores its hash and management metadata. Copy the secret directly into the approved server-side secret store before leaving the creation result. The metadata listing can identify the key later through its name, environment, prefix, suffix, scopes, timestamps, status, last-used time, expiry, and revocation fields, but it cannot reconstruct the original value.

Creation and revocation are limited by the supplied module to project owners and admins. If the backing Supabase or service-role configuration is missing, the surface can report setup-required rather than creating a usable key.

Only a project owner or admin can create a key in the supplied implementation.

Creation returns the raw secret once while storing its hash and metadata.

A setup-required state can prevent creation when the required backing services are unavailable.

Key creation produces two different outputs: the raw secret for the client and a metadata record for later management. Store the secret in an appropriate secret system immediately, because the product can identify the key later without reproducing its value.

A key reports active, expired, or revoked status.

Missing Supabase or service-role configuration can put key management into setup-required state. Owners and admins can create or revoke project-scoped keys.

Name and scope

Choose a name that identifies the caller or deployment without placing a secret in the label. Environment metadata can separate development, staging, and production use, while independent keys allow each environment to be revoked and attributed separately. The default scopes are gateway:read and gateway:invoke; the chat-completions route specifically checks gateway:invoke.

A key’s prefix or suffix is display metadata, not proof that the raw value is valid. Verification also checks the hash, active state, expiry, revocation, scope, and project context.

Key metadata can include a human-readable name, environment, scopes, prefix, suffix, timestamps, expiry, and last-used information.

Choose metadata that lets an operator identify an application and environment without embedding a secret or sensitive payload.

Names and environment labels should make ownership and intended use understandable without embedding secrets. Scopes define Ethen permissions; they do not grant access to an external provider account or replace a BYOK credential.

Metadata includes name, environment, prefix, suffix, scopes, timestamps, expiry, revocation, and last use. Keep the Ethen project key separate from provider credentials, and handle each failure before changing model or routing settings.

The raw value is generated at creation and only its hash is stored. Secret material belongs in the authorization or credential path defined by the implementation, not in URLs, payload metadata, or client-visible files.

Store keys

Store the raw key outside application source and client-visible configuration. The service’s hashed-storage design protects the management database from exposing a recoverable secret, but it does not protect copies placed in logs, shell history, screenshots, tickets, or frontend bundles. Restrict access to the component that actually sends Gateway requests.

Metadata-only listing means administrators can review status and usage without seeing the secret. That is useful for inventory and revocation, but it also makes the one-time reveal irreversible: losing the raw value requires a replacement key.

Capture the raw value at creation because it cannot be reconstructed from the stored hash.

Keep it in a server-side secret store and restrict retrieval to the calling workload.

The prefix and suffix are identification aids, not substitutes for secret handling.

The key store retains a hash plus operational metadata such as prefix, suffix, status, timestamps, expiry, and last use. A source-code file, shared document, or client-side bundle is not an appropriate storage location for the raw value.

Default scopes are gateway:read and gateway:invoke. A valid-looking prefix is not proof of a valid key; status, expiry, revocation, and scope checks still control acceptance.

Rotation should preserve an overlap period in which the replacement is tested before the previous credential is revoked.

Because the raw value is shown only at creation, the client must finish secret storage before leaving that flow. The metadata list is intentionally sufficient for administration without exposing the credential: operators can identify a key by name, environment, prefix, suffix, timestamps, scopes, expiry, revocation, and last-used state. Losing the raw value requires replacement, not retrieval.

Rotate keys

Rotation is an overlap procedure rather than a verified single-button operation. Create a replacement, store its raw value at the moment it is shown, update each caller, and verify that traffic reaches the new key through a narrow request or last-used metadata. Revoke the previous key only after dependent clients have moved. This sequence avoids turning a routine credential change into an avoidable outage.

The sources verify creation and revocation, not a dedicated rotation action. Use an overlap sequence instead. Create a replacement key, store it securely, update one caller or environment, send a minimal authenticated request, and confirm the new key’s last-used state and request attribution. Move remaining callers only after the replacement works, then revoke the old key.

Do not revoke the old key before all required callers have moved unless immediate containment is more important than continuity. The overlap is an operational procedure, not a guarantee that both keys will remain valid for a fixed period.

The sources verify creation and revocation rather than a dedicated atomic rotate operation.

A safe rotation is to create a replacement, deploy it to the caller, verify successful requests, and then revoke the old key.

Plan overlap carefully so a rollback does not require restoring a revoked secret.

Rotation is implemented safely as overlap between a new key and an old key. Create the replacement, update clients, verify the replacement through a test request or last-used state, and revoke the old key only after traffic has moved.

Default scopes are gateway:read and gateway:invoke.

Rotation can be completed without assuming a dedicated rotate control. Create a replacement key with the required project, environment, scopes, and expiry; capture the raw value during the one-time reveal; update each caller; then verify that traffic is using the replacement before revoking the old key. The stored metadata can help distinguish the two credentials through name, prefix, suffix, creation time, last-used time, expiry, and revocation state, but it cannot recover either raw secret.

An overlap period is useful because revocation is immediate from the caller’s perspective: once the old key is marked revoked, subsequent requests should fail authentication. Keep the overlap only as long as needed to migrate known clients. Do not widen scopes during rotation unless the application actually requires them, and never place the raw value in request logs, screenshots, source control, or support messages.

Revoke keys

Revocation changes the key state so future chat requests are rejected with revoked_api_key. Record which deployment used the key before revoking it, because the prefix, suffix, environment, and last-used metadata can help identify remaining callers. Revocation does not recover or reveal the raw value.

After revocation, remove the secret from deployment configuration and any approved secret store. If a caller continues to fail, confirm that it is not still loading a cached or outdated value.

Owners and admins can revoke keys, and revoked keys fail handler validation before routing.

Use the key identifier and metadata listing to select the intended credential.

Revocation is appropriate for suspected exposure, retired workloads, or completed migrations.

Revocation changes the key state and causes the verified chat handler to reject future use. Keep the key identifier and revocation time for incident review instead of deleting the only management record that explains the rejection.

Troubleshooting

If a new key is rejected, check that the complete raw value—not the displayed prefix or suffix—was deployed and that the caller is using the intended project and environment. Then inspect active, expired, revoked, and scope state. A provider credential cannot substitute for the Ethen Gateway key.

An invalid key may be malformed, unknown, or associated with unavailable backing configuration.

An expired or revoked key has a different remediation path from insufficient_scope.

If a newly created key cannot invoke, verify the project, scope, environment configuration, and exact Bearer header before changing routing settings.

Setup-required states can originate from missing platform configuration rather than the individual key. Distinguish a management surface that cannot initialize from a key that exists but is expired, revoked, or missing the required scope.

Default scopes are gateway:read and gateway:invoke.

No dedicated rotate action is established by the supplied implementation; rotation is a create-and-revoke procedure, and raw values cannot be recovered.