Bring your own key

Bring Your Own Key lets a project supply an external provider credential for eligible Gateway execution. It does not replace the Ethen Gateway key used to authenticate the inbound request, and it does not change the provider’s own account or data policies.

Provider coverage, exact controls, cryptographic implementation details, and provider-side retention or training behavior require security and legal review.

BYOK creates a three-party boundary: the application authenticates to Ethen, Ethen selects an eligible provider route, and the project credential authenticates Ethen to that provider. Each boundary has separate errors, rotation procedures, and policy implications. The verified UI statements cover project scope, encryption at rest, and non-return of raw provider keys. They do not replace the provider’s own terms, billing, retention, training, or account controls, which remain external to the inspected implementation.

BYOK overview

A provider credential may also be limited by the external account’s own permissions or model access. Ethen can store and resolve the secret without being able to guarantee that the provider will authorize a particular request.

Bring Your Own Key supplies a project-scoped credential that Ethen can use when invoking an eligible external provider. It does not authenticate the application to the Gateway. The caller still sends an Ethen project key in the Bearer header, and the runtime resolves a provider credential only after routing has selected a candidate.

The current BYOK surface states that provider credentials are encrypted at rest and that raw provider keys are not returned after creation. These statements describe Ethen’s current management surface. They do not establish how an external provider stores prompts, uses data, bills the account, or applies retention and training policies.

BYOK credentials are project-scoped and resolved before provider execution when the required encryption and credential services are available.

The inbound caller still authenticates to Ethen with a Gateway API key.

A configured provider credential does not make every model or modality runnable.

BYOK lets a project supply a provider credential for eligible outbound Gateway routes. It does not replace the Ethen API key used by the application to authenticate the incoming request.

Privacy and Terms are the only approved current legal links for this page.

The routing runtime resolves a provider credential immediately before adapter execution.

A missing credential can surface as provider_key_missing or make the provider ineligible.

Add credentials

After saving a provider credential, verify it through one minimal request and inspect the selected provider. A successful request routed elsewhere does not prove that the newly added credential was used.

Use the approved BYOK surface for the current project. Select only a provider represented by the current product controls, supply the provider credential through the secret-entry path, and capture any nonsecret identifying metadata shown after creation. Exact form labels and universal provider coverage are not verified.

Because the raw value cannot be retrieved later, store the original provider credential in the organization’s approved secret system if independent recovery is required. Do not duplicate it in ordinary project notes, application metadata, logs, or client code.

Use the approved BYOK product surface for the project rather than placing a provider secret in request metadata.

The UI states that credentials are encrypted at rest and that raw values are not returned after creation.

Exact provider choices and form labels should be verified against the current environment.

Add credentials through the verified project-scoped surface and capture the provider and project association accurately. The current evidence does not support a universal provider list or an API schema for credential creation.

BYOK credentials are scoped to a project.

The BYOK surface states that provider credentials are encrypted at rest.

Raw provider keys are not returned after creation. Rotation should preserve an overlap period in which the replacement is tested before the previous credential is revoked.

Provider mapping

A project can hold provider configuration without making every model on that provider eligible. Model aliases, account access, provider availability, policy, and modality still apply. BYOK should be described as one credential input to routing, not as a universal provider-enable switch.

Routing resolves the provider credential for the provider selected on a particular attempt. A project can still fail to run a model when the provider credential is absent, invalid outside Ethen, disallowed by policy, incompatible with the requested model, or associated with a provider that is unavailable.

Provider aliases and timeouts are separate from credentials. An alias maps the client model to a provider-specific identifier; a timeout limits the attempt; the credential authorizes the outbound provider account. Updating one does not repair the others.

Routing selects an eligible provider before resolving the project credential for that provider.

A missing provider key can produce provider_key_missing or contribute to a non-runnable route.

Do not infer a universal BYOK provider matrix from the runtime provider type list.

Provider mapping occurs during route execution. A credential for one provider does not make another provider eligible, and the runtime can still reject the route because of policy, catalog status, allow-lists, health, or modality.

Add a credential only through the verified project-scoped BYOK surface. Test one narrow request before broader use, and rotate by replacing the secret before revoking the old value.

BYOK credentials are scoped to a project.

Security model

The inbound Gateway key and the outbound provider credential protect different trust boundaries. The project key proves that the caller may invoke Ethen; the BYOK secret authorizes Ethen to call an external provider for that project. Stored provider secrets are encrypted and the raw value is not returned by the management surface. These implementation facts do not establish provider-side retention, training, residency, or compliance guarantees.

Encryption at rest protects the stored provider credential within the current Ethen surface; it does not make the credential safe to expose before submission or after copying it elsewhere. Limit who can enter or replace provider secrets and avoid displaying full values in screenshots, logs, or support records. Raw values are intentionally not returned after creation.

The external provider remains an independent trust and billing domain. Its account permissions, model access, data handling, retention, training choices, regional behavior, and charges are governed outside this implementation. Ethen documentation should not translate encrypted storage into a claim about provider-side processing.

The documented security boundary includes project scope, encrypted-at-rest storage on the BYOK surface, nonreturn of the raw value, and late credential resolution before adapter execution. Gateway request logs use metadata-only behavior in the inspected chat handler, but that statement must not be extended to every product route or external provider.

Legal links for this page are limited to the approved Privacy and Terms routes. Pending BYOK, retention, and security policy pages are not published links. Provider-side guarantees must come from the provider’s own agreement rather than being inferred from Ethen’s credential storage.

Treat the provider key as a high-impact secret with access limited to the Gateway execution path.

The supplied UI statement supports encrypted-at-rest wording but not a complete cryptographic or key-management guarantee.

Provider retention, training, billing, account restrictions, and incident response remain governed outside this documentation.

The UI states that provider credentials are encrypted at rest and that raw values are not returned after creation. Broader claims about key-management architecture, isolation, hardware security, or compliance require separate security evidence.

Two credentials participate in a BYOK request. The Gateway API key authenticates the caller to Ethen and is checked before routing. The provider credential belongs to the project, is resolved only after an eligible provider has been selected, and is used for the outbound adapter call. Passing one credential does not compensate for a problem with the other.

The verified surface states that provider credentials are encrypted at rest and that raw values are not returned after creation. That supports one-time capture and later replacement, not recovery of the original secret. The sources do not establish universal provider coverage, provider-side retention, training use, billing behavior, regional processing, or deletion guarantees. Those matters remain governed by the external provider and the project’s account with it. Rotation should create or store the replacement, confirm that the intended provider route can use it, and then revoke or remove the obsolete value without exposing either secret in logs or screenshots.

Rotation and revocation

After removing an old credential, issue a new test request that is forced only as narrowly as the verified routing controls allow, then confirm the expected provider and alias in the response metadata.

A universal credential-rotation button is not verified. Use an overlap procedure if the provider account permits multiple credentials: create or obtain a replacement at the provider, add it to the project, test one minimal route, move callers, then remove or revoke the old provider credential. Exact revocation effects depend on both Ethen configuration and the provider account.

If exposure is suspected, prioritize containment. Remove the credential from the project and revoke it with the provider according to the provider’s controls. Replacing the Ethen Gateway key alone does not invalidate a compromised provider credential.

Because raw provider keys are not returned, rotation requires a replacement credential rather than retrieving the old value.

Coordinate provider-side revocation with the project credential update to avoid an unexpected outage.

Verify successful routing through the intended provider before removing the previous credential.

Rotate by creating a replacement credential, validating a narrow provider request, and revoking the previous credential through the supported management path. Do not assume that a raw value can be viewed or exported for migration.

BYOK credentials are scoped to a project.

Credential replacement should be provider-specific. Store the new value, confirm that the mapped route can resolve it, and then remove or revoke the old record according to the available surface. A successful Gateway authentication test is insufficient because it exercises the Ethen key, not necessarily the selected provider credential.

Troubleshooting

If a route works with one provider but not another, inspect the attempt-level provider and selected alias before replacing credentials. A missing or invalid mapping can resemble a credential problem, while an allow-list or policy exclusion can prevent the credential from being used at all. Test with one eligible model and one provider restriction only after the default route is understood.

provider_key_missing indicates that the selected route lacks the required provider credential. It is different from missing_api_key or invalid_api_key, which refer to the Ethen Bearer key. Confirm the final selected provider and attempt metadata before adding a credential for a different provider.

A saved credential does not guarantee a runnable route. Check model status, provider availability, project allow-lists, policy, aliases, timeouts, and external provider validity. Do not expose the raw credential in a support ticket; use project, provider, request, trace, and redacted error identifiers.

Separate invalid inbound Gateway authentication from missing or rejected provider credentials.

If a model is catalog-only or the modality is unsupported, adding a provider key will not by itself make the route runnable.

Use provider attempts and redacted errors without copying secret material into logs or support messages.

A provider-key-missing error means the selected route lacks usable credentials in the current project and environment. It does not prove that BYOK is unsupported globally or that a different provider route is unavailable.

Compare the configured value with the observed result before continuing.

The UI states encryption at rest and one-way raw-key handling, but provider retention, training, billing, deletion, and universal BYOK support remain outside the verified contract.