Credential management

Ethen uses several kinds of credentials: Ethen API keys, external provider keys, connector credentials, identity sessions, and server environment values. They authenticate different boundaries and should not be stored, shared, rotated, or revoked as though they were interchangeable.

The current repository shows configuration checks and product-specific credential modules, but a complete managed-secret lifecycle is not established. This page describes a conservative operating model while storage encryption, access logging, rotation, revocation, and incident procedures remain under security review.

Credential types

An Ethen Gateway API key authenticates a request to Ethen. A provider credential lets Ethen authenticate to an external model, media, voice, or connector service. An identity session represents a user’s signed-in interaction. A database service credential gives server code elevated access to a backend. Encryption keys protect stored or transmitted data and are not equivalent to any of the preceding values.

Classify each secret before handling it. The classification determines where it may appear, who owns it, and what revocation means. Reusing one credential for several unrelated products increases the impact of compromise and makes attribution harder.

Environment configuration can indicate whether a value is present and reject placeholders. That check does not prove that the value was generated securely, stored in a managed vault, or restricted to the intended service.

Name the boundary before choosing the control

A credential inventory should answer three questions: who presents the credential, which service validates it, and what access follows from successful validation. That model prevents common category errors.

For an Ethen Gateway API key, the caller presents the key and Ethen validates it before allowing supported Gateway operations. For a BYOK provider credential, Ethen presents the secret to the external provider, which validates it against the customer’s provider account. For a user session, the browser presents session state and the configured identity provider establishes the user. For a Supabase service credential, trusted server code can receive elevated backend access.

The blast radius depends on the validating service and granted access. A leaked Gateway key may expose Ethen routes but not the provider console. A leaked provider key may expose the provider account even when the associated Ethen user is disabled. A leaked service-role value can bypass ordinary data policies if the application uses it broadly.

Document those consequences explicitly. “API key” is too vague for incident, rotation, or access decisions.

Storage

Raw credentials should remain server-side and should not be returned in normal responses, written to ordinary logs, embedded in URLs, or copied into client-visible configuration. Where a product reveals a newly created key once, users should store it in an approved secret-management system rather than a document or chat message.

The current credential and connection modules represent intended product behavior, but the production encryption and storage contract remains under review. Administrators must determine whether a value lives in an environment variable, database, local file, browser state, or external secret service.

A stored hash can support verification of an Ethen-issued API key without preserving the raw value. That pattern does not apply automatically to provider credentials, which may need to be retrieved for outbound authentication. The difference should be documented per credential type.

Storage decision record

Before placing a secret, record the intended storage mechanism and why it is appropriate. Public environment variables are unsuitable for server credentials because build tooling can expose them to the client. Source files, screenshots, issue trackers, and ordinary chat messages are also unsuitable because their access and retention are difficult to control.

A server environment variable can keep a value out of the client bundle, but it still leaves operational questions: who can read deployment configuration, whether values are encrypted by the host, how changes are audited, and how old versions are handled. A database or connection store introduces retrieval and ownership requirements. A local file ties the secret to a device and operating-system account.

Where raw retrieval is necessary for provider authentication, restrict the read path to the server component that performs the outbound call. Where raw retrieval is unnecessary, prefer verification patterns that avoid retaining the original secret. The application should redact secret-like values from errors and logs regardless of the store.

Access

Credential access should be narrower than access to the product that uses the credential. A user may be allowed to invoke a configured provider without being allowed to view or replace its key.

Review who can create, read, update, and revoke each secret. Include server processes and deployment administrators, not only interface users. For database service credentials, verify that the value cannot enter a client bundle. For connector credentials, confirm which workflow or route can use the connection.

Access logging is not established uniformly. If the secret-management layer does not record reads and changes, document the gap and use deployment controls to reduce the number of principals with access.

Access paths to inspect

Review deployment administrators, application servers, background workers, database roles, connector processes, and product administrators. A user interface that hides a key can coexist with broad access through deployment tooling or a service account.

Separate the ability to use a configured connection from the ability to change or reveal its credential. Most operators need the former, not the latter. If the current product cannot enforce that distinction, narrow access at the deployment or provider account.

For shared provider accounts, identify whether activity can be attributed to a project or Ethen key. Without stable attribution, incident response may show that the provider credential was used without revealing which customer action triggered it.

A quarterly or event-driven credential review should compare the inventory with active deployment values and provider accounts. Remove credentials that have no owner, no recent justified use, or no known route. Reissue shared values when individual accountability is required.

Because automated credential access review is not established, the organization should decide who performs this comparison and where the result is retained. The review should never expose raw values to people who only need metadata.

Rotation

Rotation replaces a credential while minimizing interruption. A dedicated rotation control is not verified across Ethen products, so use a staged manual pattern where the provider supports overlapping credentials.

Create a replacement in the provider account, configure it in the intended server-side location, verify the affected route with non-sensitive input, and only then revoke the old value. Record the owner, date, affected products, and verification result.

Some providers allow only one active key or propagate changes slowly. In that case, plan a maintenance window and define rollback before revocation. Do not claim that Ethen automatically updates every workflow, local store, or deployment when a credential changes.

Rotation validation

A successful cutover should prove more than “the settings page accepted the new value.” Test the exact provider or connector route, confirm that the expected account and capability were selected, and inspect the returned request or provider identifier. Then revoke the old key and repeat a request that should now fail if an old deployment still uses it.

Search all configured environments for the previous value or its identifier. Development laptops, preview deployments, CI variables, and local workflow stores can retain copies after production is updated. If the provider exposes last-used information, use it to detect a forgotten client.

Document rollback separately from indefinite overlap. Keeping two keys active forever removes the assurance rotation was meant to provide.

Revocation

Revocation should occur when a credential is exposed, an owner changes, a provider account is closed, or the credential is no longer needed. Remove the value from Ethen configuration and revoke it at the issuing system. Either step alone may be incomplete.

For an Ethen-issued API key, confirm that the route rejects future use after revocation. For a provider key, test the configured provider path after the provider confirms invalidation. Check development, staging, local, and automation environments for copies.

Historical logs and requests may remain after revocation. Revocation prevents future authentication; it is not a deletion mechanism for data previously processed by the provider.

Revocation outcomes

After revocation, verify the outcome at the issuer. A provider account should reject the old credential; an Ethen-issued key should fail at the Ethen authentication boundary. A removed environment value may require a deployment restart before the process stops using it.

If the credential authorized a durable connection record, mark or remove that connection so the interface does not continue to present it as ready. If a workflow or route can fall back to another credential, confirm the new destination before resuming sensitive traffic.

Keep a record of the affected products and the evidence used to confirm invalidation. Do not include the secret itself.

Revocation should also update readiness state. A connection or provider route that no longer has a valid credential should become setup required, unavailable, or otherwise non-runnable rather than continuing to appear healthy. This state change helps operators distinguish intentional revocation from an unexplained provider outage.

Where the product lacks that automatic transition, record the configuration change and warn users before they retry the route.

Incident handling

When a credential may be compromised, first limit further use. Revoke or disable it at the issuer when that action is available, then remove exposed copies and replace the value only after the affected boundary is understood.

Collect the credential type, owner, affected provider or route, first and last known exposure, relevant request identifiers, and any suspicious activity visible in provider or Ethen records. Never include the raw secret in the incident record.

A formal Ethen credential-incident workflow and response SLA are not established. Use the approved Help or Contact route for product assistance, and follow the provider’s own security process for its credential. Preserve the distinction between contacting support and receiving a guaranteed incident response.

Exposure triage

Treat a credential as exposed when it appears in a public repository, client bundle, log, screenshot, support message, or system controlled by an unauthorized person. Do not wait for confirmed misuse before revoking a high-impact secret.

After containment, review the issuer’s activity records, Ethen request or usage records, deployment history, and code paths that handled the value. Determine whether the issue was storage, access, logging, transport, or user behavior. Correct the path before issuing the replacement.

Provider and Ethen investigations can have different evidence. Pair times and identifiers where possible, and state plainly when a complete audit trail is unavailable.