Provider keys and how they are stored

Add, replace or remove a provider's API key or AWS credentials, and what protects stored keys, including why you must keep the master key.

For: Administrators (the admin ability) · Last updated

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. The one exception is Amazon Bedrock with Use the server's IAM role, which signs requests with the AWS credentials of the server itself and stores nothing (see Amazon Bedrock credentials). You need the admin ability.

Add or replace a key#

  1. On the provider's row, select Edit.
  2. Type the key in the API key field (or paste a new one to replace the stored key).
  3. Select Save changes. 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 "Provider updated, but fetching its models failed:" followed by the reason. The key is kept either way.

If you change the Type in Edit, you must enter a key for the new type: the stored key belongs to the old provider and is never sent to another provider's address. (A type that needs no key, such as Ollama, drops the old key instead.)

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.

Amazon Bedrock credentials#

An Amazon Bedrock provider has one of three authentication options, chosen in Edit or when you add it:

  • Use the server's IAM role. Nothing is stored. The Key column reads "IAM role".
  • Access keys. The access key ID, secret access key and optional session token are stored together, encrypted. The Key column shows the masked access key ID.
  • Bedrock API key. The key is stored encrypted like any other provider key, and the Key column shows it masked.

To change credentials, select Edit, enter the new values and select Save changes. When you keep the same authentication option, leave the secret fields blank to keep what is stored. When you switch to a different option, enter that option's credentials; the previous secret is discarded. Changing the Type of a Bedrock provider to anything else also deletes its stored secret and sets it to inactive.

See Use AWS Bedrock for the options in full.

Azure OpenAI and Google Vertex AI credentials#

  • Azure OpenAI stores one API key, encrypted like any other provider key. The endpoint, API version and deployments are settings, not secrets. The Key column shows the masked key.
  • Google Vertex AI stores the whole service account key file, encrypted. The Key column shows the masked service account email, never the key. The file must be a service account key (its type is service_account); other credential files are refused.

To change either, select Edit, enter the new value and select Save changes. Leave the key field blank to keep the stored one. For Azure OpenAI, changing the Endpoint also requires entering the API key again, so the stored key is never sent to a new address without you re-entering it. See Use Azure OpenAI and Use Google Vertex AI.

Remove a key (deactivate)#

Turn off the Active switch on a provider's row. A confirmation pop-up appears before the change takes effect. Confirming 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. A Bedrock provider that uses the server's IAM role has no key to delete; turning off the switch only sets it to inactive.

Deactivating is refused when:

  • the provider backs the company default model, the default small 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.

If the provider backs the default image generation model, deactivating it clears that default.

To bring a keyed provider back, select Edit, enter the new key and select Save changes. A keyless endpoint, or a Bedrock provider that uses the server's IAM role, comes back by turning on its Active switch (see Testing, activating and removing a provider).

How keys are protected#

Stored keys, including Bedrock access keys and Bedrock API keys, Azure keys and Google service account key files, are encrypted at rest with AES-GCM under your company's data key. That data key is itself encrypted with 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 data 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 or malformed, in every environment.
  • Keep a separate copy of the master key. Database backups contain only encrypted values. If the master key is lost, or replaced without following the rotation procedure, the stored provider keys (and the stored email password) cannot be decrypted. You would then replace each key by hand. To change the master key safely, see Rotate the master key.
  • 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.
  • Adding, replacing and deleting a provider key is recorded in the audit log with who did it and which provider, never the key.