Authentication

Authentication for the verified chat-completions route is based on a project-scoped Gateway key presented as a Bearer token. This guide explains the checks the handler performs and the boundaries that matter when a key is missing, expired, revoked, or under-scoped.

The key system is implemented, but setup-required states and the manifest’s GA label still require release verification.

Authentication troubleshooting should stay separate from provider troubleshooting. A request that fails because the key is missing, invalid, revoked, expired, or under-scoped has not reached provider routing. No change to provider order, model alias, BYOK credential, or timeout can repair that failure. Conversely, a valid Ethen key does not prove that the selected provider has usable credentials. Keeping those two credential domains separate reduces accidental key exposure and makes error handling more precise.

Authentication model

Authentication also establishes which project budget and provider configuration will be evaluated later in the request path. Using a key from another project can therefore produce a valid authentication result with a different set of routes, policies, and usage attribution.

A Gateway key authenticates the caller to Ethen and establishes project context. It is not the same credential used by an external model provider. The public chat handler validates the Ethen key before it evaluates the model route, while a BYOK credential is resolved only after a provider has been selected. Passing a provider key in the Bearer header therefore does not satisfy Gateway authentication.

The key service verifies a stored hash and evaluates metadata such as status, expiry, revocation, scopes, project membership, and the user’s relationship to the project. An accepted key contributes project, user, and key identifiers to request logs and usage events, which allows operational attribution without retaining a recoverable raw key.

Gateway keys belong to projects and are verified from a stored hash rather than a recoverable raw secret.

The chat handler connects the accepted key to project, user, and key identifiers used by logs and usage records.

Project visibility and key-management operations depend on membership and owner/admin authorization in the supplied key module.

Gateway authentication establishes the Ethen project and key context before model routing. Provider credentials are a separate outbound concern and cannot be substituted for the project key expected by the public chat handler.

A valid key without gateway:invoke receives an insufficient-scope error. BYOK provider credentials are resolved later for a selected provider and do not replace Gateway authentication.

Project visibility is limited to projects the user owns or belongs to. Authentication errors occur before provider execution, so retrying against another provider cannot repair them.

Check the configured value against the returned state before changing another setting. The service verifies a stored hash rather than comparing a recoverable raw key.

Bearer tokens

The supported header is:

Authorization: Bearer YOUR_ETHEN_GATEWAY_KEY
Content-Type: application/json

A missing header produces missing_api_key. A value that cannot be verified produces invalid_api_key. Keys explicitly revoked or past their expiry produce revoked_api_key or expired_api_key. These results occur before route selection, so a provider retry cannot change them.

Keep the token in a server-side secret store. Do not embed it in a browser bundle, query string, model name, metadata field, or repository file. If exposure is suspected, create a replacement and revoke the exposed key rather than waiting for its expiry.

Send the secret in Authorization with the Bearer scheme.

The handler separates a missing token from an invalid token and does not accept a key merely because its prefix looks valid.

Do not place a Gateway key in a query string, model identifier, metadata object, or client-visible repository file.

Header form

The Bearer value is the Ethen project key. A provider credential configured through BYOK does not replace this header.

The Bearer token is the raw key value revealed during creation. The service verifies its stored hash and key metadata, which allows revocation and expiry checks without retaining a recoverable copy of the secret.

Revoked and expired keys are rejected before model routing begins. Keep the Ethen project key separate from provider credentials, and handle each failure before changing model or routing settings.

Request headers

Treat the response correlation headers as diagnostics, not credentials. They may be logged with the request outcome, while the Bearer value must remain secret.

Authorization is required for POST /api/gateway/v1/chat/completions.

The response can include request, trace, stream, and model-status headers that help correlate execution.

The inspected models endpoint does not enforce authentication, which should not be generalized to other routes.

Place the credential in the Authorization header and keep it out of URLs, logs, browser history, and request payloads. This convention also makes missing-key errors distinguishable from malformed JSON or model-selection failures.

The verified header form is Authorization: Bearer <key>.

Key scope

The inspected chat route requires gateway:invoke. New keys default to gateway:read and gateway:invoke, but the sources do not define a universal scope vocabulary for every current or future route. A valid and active key that lacks invoke permission receives insufficient_scope.

Scope should be evaluated separately from project membership and provider readiness. A user may be able to see a project without holding a key that can invoke the Gateway, and a correctly scoped Gateway key may still encounter provider_key_missing when the selected outbound provider lacks credentials.

The verified invocation check requires gateway:invoke.

New keys default to gateway:read and gateway:invoke, but the available scope vocabulary should not be expanded beyond the source.

A valid, active key without invoke scope fails before routing.

Default key creation also includes gateway:read, but the source bundle does not establish how every other route evaluates scopes or whether administrators can define arbitrary scope combinations.

The verified header form is Authorization: Bearer <key>.

Security guidance

Key inventory should be reviewed through metadata rather than secret disclosure. Expired and revoked keys should remain distinguishable from active keys so operators can explain failures without recovering the original value. Last-used timestamps can help locate callers that still depend on an old key, but they do not reveal the request payload.

Use independent keys when environments, services, or owners need separate attribution and revocation. One shared key makes it harder to identify the affected caller after exposure and increases the number of deployments that must change during rotation. The available metadata—name, environment, prefix, suffix, scopes, last-used time, expiry, and revocation—supports that separation without revealing the secret.

Do not log the Authorization header. Request logs already carry the API-key identifier needed for correlation. When a key is replaced, verify the new caller through its request log and last-used state before revoking the previous value. If the management surface reports setup-required, resolve the backing configuration rather than copying the token into alternate fields or bypassing verification.

Store the one-time raw key in an approved secret store and expose it only to the server component that calls the Gateway.

Use separate keys where environments or operational ownership need independent revocation and attribution.

Revoke a key when exposure is suspected; do not wait for expiry to contain a known leak.

Key hygiene includes restricted distribution, environment separation, planned expiry, and prompt revocation after suspected exposure. None of those practices changes the one-time reveal rule or allows recovery of a previously created raw key.

Secret material belongs in the authorization or credential path defined by the implementation, not in URLs, payload metadata, or client-visible files.

Store Gateway keys only in the application’s secret-management path and inject them at request time. A key prefix or suffix is suitable for identification, but neither is authentication material. Limit scope and expiry to the caller’s actual need, revoke credentials that are no longer used, and avoid sharing one project key across unrelated environments when separate keys can provide clearer ownership and last-used history.

Errors

Authentication failures should be separated before model or provider troubleshooting begins. A missing or malformed Bearer header is a request-authentication problem. An unknown hash, revoked key, expired key, or missing gateway:invoke scope is a credential-state problem. Provider credentials are checked later during routing and cannot repair an invalid inbound Gateway key.

When multiple key records exist, verify the key ID associated with the failed request rather than assuming the most recently created key was used. Deployment caches and environment variables can continue to supply an older value after a management change.

Authentication error handling can remain deterministic:

Do not mask these errors with automatic provider fallback. None of them represents a provider failure.

missing_api_key means the Authorization credential was absent or unusable at extraction time.

invalid_api_key, revoked_api_key, expired_api_key, and insufficient_scope represent distinct validation outcomes.

setup_required can indicate that the backing key service is not configured, so replacing the token alone will not resolve it.

Authentication errors should be handled before retry or routing changes. A revoked or expired key needs a replacement; insufficient scope needs a correctly scoped key; an invalid key should not be repaired by changing the model or provider.

The inspected handler verifies gateway:invoke; the supplied sources do not establish a universal public scope matrix for every Gateway route.

Authentication errors describe different key conditions and should not be collapsed into one “unauthorized” diagnosis. missing_api_key means the request did not provide an acceptable Bearer credential. invalid_api_key covers a value that cannot be matched to a stored hash. Revoked and expired keys retain their identity but are no longer usable, while insufficient_scope means the key is valid yet lacks gateway:invoke.

These checks authenticate the inbound Ethen request. They do not prove that an outbound provider credential exists. BYOK resolution occurs later, after routing selects an eligible provider, so a request can pass Gateway authentication and still fail because the chosen provider is not configured. Project membership also affects key visibility and management: the inspected implementation limits projects to those the user owns or belongs to and restricts creation or revocation to owners or admins. The security review flag remains because these source-level rules are not a complete public identity or authorization specification.