API Key Management

Adding an API key#

1. Go to Settings → Model Configuration
2. Select your provider
3. Paste your API key
4. Click Save

Saving validates the configuration and stores the encrypted key. A connection probe is a separate provider request; a save does not establish model compatibility or token-count accuracy.

Declared Messages-protocol endpoints#

To use your own public HTTPS endpoint that speaks the Messages protocol, register a route through the model-config API with provider anthropic, your model identifier, an explicit baseUrl and the endpoint's API key. This route accepts a non-empty key of at least 10 characters; without a declared endpoint, the default Anthropic route still requires its normal sk-ant- key format.

The declared baseUrl must include a non-root API path. A bare host or root path is rejected with 400 invalid_request and details.fields: ["baseUrl"]; LumenFlow does not rewrite it. The Messages SDK appends /messages to the configured path, so paths such as /v1, /proxy/v1beta or /gateway/messages-api are preserved. Without an explicit baseUrl, the default endpoint is unchanged.

Only public HTTPS destinations are allowed. Private, loopback and metadata addresses are refused. Changing the endpoint origin requires you to supply the API key again. An endpoint declaration never enables access to a private network.

Optional per-call admission caps#

A governed inference caller can send max_cost_usd to request pre-call admission against a provider-estimated worst-case charge. It is a positive USD number with at most six fractional digits, within the workspace's resolved registry ceiling, which the platform sets. Scientific notation is accepted only when applying the exponent leaves at most six fractional digits and an exact positive micro-USD amount: 2.49e-4 is accepted, while 1e-7 is refused. Over-precise wire values are refused before number rounding. This is not a promise that the final provider cost stays below the cap. Without the field, existing calls behave as before. The full request contract, streaming and refusals are in Governed inference API.

Capped calls need an explicit transport profile, even for a native endpoint. Through the model-config API, supply transportProfile: "anthropic-messages-passthrough" and transportProfileAttested: true together. Setting transportProfileAttested attests the configured Messages protocol, exact endpoint, model, API version and output limit, including reasoning. Supply both fields again on every save or key rotation; omitting them clears eligibility. If compromise is suspected, revoke the provider key at the provider too. A provider family, model name or capability declaration alone does not make a route eligible.

All authorized model-config PUT saves and rotations commit the configuration and audit together; an audit outage returns 503 audit_unavailable and leaves the configuration unchanged.

Before generation, LumenFlow sends your input to the same endpoint for a token estimate. Counting therefore sends your prompt before admission; its charging and quota terms depend on your endpoint. A successful count is still an estimate, and your attestation does not prove accuracy or count success. Only verified ordinary text and client-function-tool mappings are admitted; unknown shapes, unsupported transports, missing profiles and failed counts refuse. Capped calls are available on supported routes only.

The estimated input and the output cap are combined into the admission estimate. Refusals, aborts and timeouts cancel pending work. Your provider's actual BYOK usage and cost remain visible even above the caller cap.

Key security#

Your API key is encrypted with industry-standard encryption before storage. The encryption is workspace-specific, so keys cannot be accessed across workspaces. Encryption keys are stored separately from your data, providing multiple layers of protection.

Rotating keys#

To rotate your API key:

1. Generate a new key from your provider's dashboard
2. Go to Settings → Model Configuration
3. Click Update Key
4. Paste the new key
5. Save. New calls use the new key.

Calls already selected or running may continue briefly. Revoke the old key at your provider if you need to withdraw its access.

Declaring token prices#

The model-config API accepts declaredPrices with inputPerMillion and outputPerMillion, plus optional cachedInputPerMillion for cache reads and cacheWritePerMillion for cache writes. Rates are USD per million tokens, from 0 to 10000. An omitted cache-read or cache-write rate uses the input rate.

These are your own estimates of what your provider charges. The provider bills you directly for model usage. Governed inference reports the declared cost with basis byok_declared, and its receipt records cached-input and cache-write token counts. A declared price is not verification of a provider's invoice or compatibility.

Declaring where your endpoint runs#

When you connect a custom OpenAI-compatible endpoint you can declare the region it runs in (eu_west, us_east, us_west or apac) under Endpoint region (declared by you). This is your own statement about your endpoint. Keep it accurate. A pinned workspace's model calls compare this declaration with its pinned key region. If no valid endpoint region is declared, the hosted-provider default is used for that comparison; a mismatch is refused before dispatch. Rotating the key keeps the declared region, and changing the provider or the endpoint clears it until you declare it again.

For a declared Messages endpoint, set the same endpointRegion declaration through the model-config API. The same residency checks apply before any provider request.

Revoking access#

If you suspect a key is compromised:

1. Revoke the key at your provider's dashboard immediately
2. Update the key in LumenFlow settings
3. Check the audit trail for unexpected actions

Model-pinned judgment checks#

Some governed operations can use a judgment check with a pinned model. A trusted tenant and workspace policy must enable the exact purpose and provider; a purpose mapping or credential alone cannot enable it. The judgment check may use either a managed or an approved workspace BYOK source, so "local" does not guarantee on-device processing. Data is sent only when its purpose, provider and input all permit the request. A timeout, malformed answer, missing serving identity, or different model identity is refused. External providers remain disabled unless the trusted tenant policy explicitly enables them; a platform credential supplies authentication only.