BYOK security and operations

Bring Your Own Key allows a customer to supply a provider credential for supported Gateway or product routes. It changes who owns the provider account and credential; it does not create customer-managed encryption, bypass Ethen’s request path, or establish provider retention and training guarantees.

Use this guide to operate BYOK conservatively while credential storage, provider policy, lifecycle automation, and monitoring remain under review. The Gateway BYOK surface is verified, but universal provider support and a production secret-management contract are not.

BYOK model

A BYOK request involves two authentication boundaries. The caller authenticates to Ethen with an Ethen-issued key or user session where the route requires it. Ethen then authenticates to the external provider with the customer-supplied provider credential.

Those credentials should never be confused. Revoking the Gateway key stops that Ethen caller; it does not revoke the provider account. Revoking the provider key stops provider authentication; it may leave the Ethen API key valid for other configured routes.

The provider remains responsible for its service behavior, account entitlements, availability, and data policies. Ethen remains responsible for using the configured credential only through supported routes and avoiding raw-key disclosure in responses or ordinary logs.

Request-path example

A client sends a supported Gateway request using an Ethen credential. Ethen authenticates the caller, evaluates model or route readiness, applies relevant policy and budget checks, selects an eligible provider, and uses the configured provider credential for the outbound request. The response and supported operational metadata return through Ethen.

This path means BYOK is not a direct browser-to-provider connection. Ethen still processes the request fields required for routing and response handling. At the same time, the customer’s provider account controls provider entitlement and external charges.

If the selected provider is unavailable or the account lacks model access, a valid BYOK secret can still fail. If fallback is configured, the destination may change. Data-handling review should cover every provider that can become eligible.

Credential lifecycle

The lifecycle begins before the key is entered into Ethen. The customer should create a provider credential in the intended account, apply provider-supported scope restrictions, identify the business owner, and record the routes allowed to use it.

During configuration, keep the value server-side. After setup, verify the provider and model with low-risk input. A readiness indicator confirms only what that indicator actually checks; it may not prove every model, region, quota, or data-policy requirement.

At the end of use, remove the Ethen-side configuration and revoke the provider credential. No universal automated offboarding workflow is established, so customers should track BYOK credentials outside the product until the lifecycle is fully implemented.

BYOK inventory fields

Track each provider credential with:

• provider and account owner;
• environment and Ethen product;
• permitted model or capability, when the provider supports scoping;
• storage mechanism;
• creator and operational owner;
• creation and last review date;
• rotation or expiry expectation;
• revocation method;
• provider policy reference;
• Ethen routes allowed to use it.

This inventory is necessary because a settings surface cannot prove that no duplicate exists elsewhere. A key can be copied into a local deployment, preview environment, or another product without changing the visible production record.

Do not store the raw value in the inventory. Use a provider-side identifier, label, or final characters when the provider supplies a safe reference.

Onboarding decision

Before adding BYOK, confirm that the provider and capability are approved for the data class, the customer account has the required entitlement, and the product route supports that provider. Identify whether the credential is shared across projects or dedicated to one workload.

Run the first request with non-sensitive input and verify the provider, account, model, and operational metadata. A successful interface save is not enough; the outbound route must authenticate and return the expected capability.

Document who can replace the value and who can approve a provider change. If no durable ownership record exists in Ethen, retain it in the customer’s approved operational system.

Provider access

Provider access depends on more than possession of a valid key. The customer account may lack access to a model or modality, the provider may be unavailable, a policy may block the route, or a budget check may stop the request.

Review the provider’s current terms for retention, training, regional processing, subprocessors, and security. Ethen documentation does not assert zero retention or zero training. The provider’s account settings and contractual terms remain authoritative for those questions.

If a product supports routing or fallback among providers, confirm whether the BYOK credential is used for all eligible routes or only one provider. Do not assume a fallback stays within the same account or data boundary.

Eligibility versus readiness

Separate four states during diagnosis:

1. credential present — Ethen has a configured value;
2. provider authenticated — the provider accepts that value;
3. capability entitled — the account can use the requested model or service;
4. route runnable — Ethen policy, limits, provider health, and product state permit the operation.

A settings check may verify only the first state. A low-risk test can verify authentication and entitlement for one capability, but it cannot guarantee every model, region, or future provider condition.

Provider account restrictions can be beneficial. Use provider-supported scopes, project separation, spending controls, or model allow-lists where available, but do not describe them as Ethen controls unless Ethen implements and enforces them.

Data-policy checkpoint

Provider access should remain blocked for sensitive production data until the customer has reviewed the provider’s current retention, training, regional processing, and subprocessor terms. Ethen does not substitute its own documentation for those provider commitments.

If the provider offers enterprise controls such as project separation or restricted keys, configure and verify them in the provider account. Describe them as provider controls, not native Ethen features. Revisit the review when the provider, account tier, region, or model changes.

A provider being listed or selectable in a product does not mean the provider is approved for every customer workload.

Rotation

Plan rotation around the provider’s capabilities. When overlapping keys are supported, add the replacement, validate it through the intended Ethen route, monitor for authentication failures, and then revoke the previous key.

When overlap is not available, schedule a controlled cutover. Record which deployments and products use the value so an old copy is not left in a local environment or background process.

A visible BYOK page does not prove a dedicated Rotate button or automatic propagation. Treat rotation as manual unless the exact product source documents otherwise.

Cutover without silent fallback

When validating a new key, temporarily use a request whose intended provider can be confirmed from the supported response or log metadata. Otherwise, a fallback can make the test appear successful while the replacement key is invalid.

After revoking the old key, check for authentication failures from forgotten environments. A sudden error in a development or scheduled process can identify an untracked copy. Resolve those copies rather than reactivating the old key broadly.

If the customer cannot tolerate interruption and the provider offers no overlapping credential, document the maintenance window and rollback decision before starting.

Expiry planning

If the provider credential has an expiry, schedule replacement before the date and identify every deployment that uses it. An expired key can look like a provider outage when ownership is unclear. Record the expiry in the inventory, not in ordinary product logs.

Where the provider supplies no expiry, periodic review still helps detect orphaned or over-broad credentials. Review is not the same as forced rotation; unnecessary replacement can create outages without reducing risk when storage and access remain unchanged.

Monitoring

Monitor both Ethen and provider signals. Ethen may expose request IDs, provider selection, route status, errors, latency, or usage for supported Gateway operations. The provider account may expose authentication failures, quota events, usage, or account changes.

These records are not a complete credential-access audit. The platform’s general audit route is sample based, and product logs vary in persistence and content. Avoid claiming that every credential read, provider call, or configuration change is durably recorded.

Set alerts in the systems that actually provide them, and document which evidence source is authoritative for an investigation.

Signals and blind spots

Ethen-side signals can show which route, model, or provider a supported request used, together with errors, latency, attempts, usage, or fallback metadata where implemented. Provider-side signals can show account authentication, service usage, quota, and billing. Neither side alone necessarily explains the whole path.

A complete secret-access history is not available. The general audit surface uses fixtures, and not every configuration read or outbound attempt emits a durable event. Administrators should therefore protect configuration access at the deployment layer and use provider alerts where offered.

Unexpected usage should trigger both an Ethen-key review and a provider-key review. The caller credential and outbound credential are separate compromise paths.

Ownership changes

Review BYOK configuration when the provider account owner leaves, a project transfers, or the provider changes account structure. A credential can remain technically valid while no current administrator understands its origin or permitted use.

Transfer ownership through the provider’s approved controls, rotate the key when appropriate, and update the Ethen and external inventories. Do not leave an orphaned shared credential as the only runnable route.

Review provider-account alerts after rotation and after major routing changes. A new model or fallback path can generate usage under the same credential without appearing as a credential change. Correlate provider activity with Ethen request metadata where that metadata is available.

Failure recovery

Classify the failure before replacing the key. An invalid or revoked credential requires provider-account action. A setup-required state can indicate missing configuration. A model-access error may mean the account lacks entitlement even though authentication succeeded. A provider outage should not be treated as credential compromise.

For recovery, preserve the Ethen request identifier, provider name, selected model or capability, returned error, and approximate time. Test with a low-risk request after remediation. If the route supports fallback, verify the destination before allowing sensitive data to continue.

If exposure is suspected, revoke first and investigate second. Provider reporting and Ethen support use different channels, and neither currently carries a documented response-time commitment.

Recovery decision table

Do not rotate credentials as a generic response to every provider error. Rotation creates operational risk and does not fix entitlement, policy, availability, or model-name problems.

After recovery, confirm the selected provider, account, request result, and expected usage record. Keep the page in draft review until storage and provider policy questions are resolved.

Post-recovery review

After service is restored, determine whether the failure exposed a lifecycle weakness. An expired key without an owner suggests inventory problems. A valid key used by the wrong project suggests access or scope problems. A silent fallback to an unapproved provider suggests routing-governance problems.

Update the credential inventory, route documentation, and monitoring plan based on the actual cause. Do not close the issue merely because a later test succeeded.