Skip to main content

API key unreadable after a move

This page is for a site that worked, and whose AI connection broke after the site was moved to another server, deployed to a new environment, or started to run under another account or app pool.

The AI connection is broken after a move​

The status of the chat profile is Problem, and an administrator sees The API key for OpenAI no longer works. Check and replace the key in the settings of OpenAI. Everyone else sees AI is temporarily unavailable. Your administrator has been notified. See AI connection problems.

Cause​

There are two ways in which the key can be lost. Which one applies depends on where the key is stored.

The key is stored in an Umbraco.AI connection. Umbraco.AI encrypts such a key with .NET Data Protection. Without a pinned key ring, .NET keeps the keys in the profile of the account that the site runs under, and ties them to the content root path. Move the site, change the account of the app pool, or start it where the profile is not loaded, and the key can no longer be decrypted. The backoffice then shows the raw, encrypted value, and saving that value encrypts it a second time. After that the connection is permanently broken until you enter the key again. The same key ring also protects login sessions.

The key is stored by the setup wizard. The wizard does not put the key in the connection. It writes it to appsettings.{Environment}.json in the content root, under Umbraco:AI:Secrets:OpenAiKey, and the connection Aivie OpenAI refers to that setting. This key does not depend on Data Protection, but it is lost when that file does not come along: a deployment that overwrites the file, or a new server that runs under another environment name and therefore reads another file.

Fix​

Which steps you need depends on where the key was stored. If the setup wizard set it, do steps 1 to 3 and 5. If you typed it into your own Umbraco.AI connection, do steps 1, 4 and 5.

  1. Pin Data Protection, if you have not done so yet. Follow Pin Data Protection, and put the key folder in your backups. With more than one server, use a shared location. Without this step the problem comes back at the next move.
  2. Enter the OpenAI key again. Open Configuration → Setup, type the key in the field OpenAI secret key and press Set up Aivie. As the wizard explains, an empty field keeps the existing key and a filled field replaces it. See Required fields.
  3. Press Restart site in the result box and confirm. Umbraco.AI only reads the new key after a restart.
  4. If you stored the key directly in a connection yourself, open that connection under AI → Connections and type the key in again. Do not save the value that the backoffice shows you.
  5. Open Account → Subscription and press Test connection. The status should turn to OK.
warning

Do not press Save on a connection that shows an unreadable value. Saving it encrypts the unreadable value once more, and you cannot undo that. Type the key again first.

If the file appsettings.{Environment}.json does not come along with your deployments, keep the key somewhere your deployment does supply, for example as an environment variable Umbraco__AI__Secrets__OpenAiKey, or run the wizard after each deployment. The wizard writes the key as plain text to that file, so keep the file out of source control. See What the wizard writes to appsettings.