Provider keys and how they are stored

Provider keys are entered in Settings, Administration, Model Providers. They enter the system only this way; the product does not read provider keys from environment variables. You need the admin ability.

Add or replace a key#

1. On the provider's row, select Add key (or Replace key if one is stored).
2. Paste the key into the field. The placeholder reads "paste API key" or "paste new key to replace".
3. Select Save. Select Cancel to back out.

A key must be at least 8 characters. After you save, the provider becomes active and its model list is fetched again. If fetching fails, a message reads "Key stored, but fetching models failed:" followed by the reason. The key is kept either way.

You can also replace a key from Edit: type a new key in the API key field and select Save changes.

The Key column then shows a masked label: the first six characters, an ellipsis and the last three (a key of 12 characters or fewer shows only dots). Keys are never displayed in full again. If you lose a key, issue a new one with the provider and replace it here.

Remove a key (deactivate)#

Select Deactivate on a provider's row. This deletes the stored key and sets the provider to inactive, so nothing is routed to it. The provider and its settings remain in the table.

Deactivating is refused when:

• the provider backs the company default model or the company default embeddings model. Change or clear the default first (see Default models); or
• a knowledge base was created with this provider's embedding model. A knowledge base keeps using the embedding model it started with.

To bring a keyed provider back, add a new key. A keyless endpoint comes back with Activate (see Testing, activating and removing a provider).

How keys are protected#

Stored keys are encrypted at rest with AES-GCM, using a master key that comes from the deployment's environment as WI_MASTER_KEY. A key is decrypted only at the moment the product calls the provider. The same master key protects the outgoing-email password (see Outgoing email).

• WI_MASTER_KEY is a base64-encoded AES key. The server refuses to start if it is unset, in every environment.
• Keep a separate copy of the master key. Database backups contain only encrypted values. If the master key is lost or changed, the stored provider keys (and the stored email password) cannot be decrypted. You would then replace each key by hand.
• If the master key is missing on a running instance, saving a key fails with the message "WI_MASTER_KEY is not configured on this instance — key custody is disabled."
• Do not paste a provider key anywhere other than the key field; no screen shows it back.