API keys and Named Credentials | AI Engine Help Center

Where your AI provider API key is stored, who can use it, and how to rotate it safely.

AI Engine works on a bring-your-own-key basis: you hold the account with your AI provider and the API key. The key is stored in Salesforce's own credential store, not in AI Engine. This article explains how that works and how to manage the key. For first-time setup steps, see Connect your AI provider.

Where the key lives#

Salesforce splits a provider connection into two parts:

An External Credential holds the secret. The API key is sent in a custom header defined on it (see the table below).
A Named Credential holds the provider URL and points to the External Credential.

In the Org Profile you type only the name of the Named Credential. AI Engine calls the provider through that name, and Salesforce adds the key to the request when it is sent. As a result:

The key is not stored in AI Engine's code, settings or records, and does not appear in the admin panel.
AI Engine users do not see the key. Anyone who can view the External Credential in Setup can see a key typed directly into a header value, so see the tip below.
Cloud Connected does not receive your key, and nobody at Cloud Connected or a partner needs it. Keep it within your own team.

Provider	Named Credential URL	Key header on the External Credential
OpenAI	`https://api.openai.com`	`Authorization` = `Bearer YOUR_KEY`
Anthropic	`https://api.anthropic.com`	`x-api-key` = `YOUR_KEY`
Azure OpenAI	`https://YOUR_RESOURCE.openai.azure.com`	`api-key` = `YOUR_KEY`

Tip: keep the key out of view in Setup. Instead of typing the key into the header value:

Add the key as an authentication parameter (for example ApiKey) on the External Credential's principal.
Make the header value a formula that references it, for example {!'Bearer ' & $Credential.YOUR_EXTERNAL_CREDENTIAL.ApiKey} for OpenAI.
On the Named Credential, select Allow Formulas in HTTP Header.

Salesforce stores principal parameters encrypted and does not display them after saving.

Who can use the credential#

Three things must be in place for a user's request to reach the provider. Set them up in this order:

Allow the package to use the Named Credential. AI Engine is a managed package in the CloudConnected namespace. In Setup → Named Credentials, edit the Named Credential and, in the Managed Package Callout Allowlist section, enter CloudConnected in Allowed Namespaces for Callouts. Save.
Grant principal access. Everyone who uses AI Engine, admins included, needs access to the External Credential's principal. The packaged AI Engine permission sets come from a managed package, so use a permission set of your own: in Setup → Permission Sets, open or create it, go to External Credential Principal Access, click Edit, add the principal, save, and assign it to the same users. See Connect your AI provider, step 3.
Check Read access to User External Credentials. Salesforce requires it for the callout. The AI Engine User permission set already includes it; if you use a cloned permission set, add it there.

If one of these is missing, AI requests fail even for users who have the AI Engine permission sets. See Troubleshooting below.

Rotate the key#

For a planned rotation, avoid downtime by overlapping the keys:

Create the new key in your provider account. Don't revoke the old one yet.
In Salesforce, open the External Credential and replace the key: in the custom header value, or in the principal's authentication parameter if you followed the tip above. Keep the same Named Credential name, so the Org Profile needs no change.
Test with a normal user account, not only as an admin: ask a chat question and run one record action, such as Next Steps.
When both work, revoke the old key in the provider account.

If you believe a key has been exposed, revoke it at the provider first and accept a short interruption, then create a new key and add it in Salesforce.

Keep a second provider ready#

Switching provider is a configuration change: in the admin panel's Org Profile, pick another AI Provider, AI Model, Fast model (internal steps) and Named Credential, then click Save. The fast model must belong to the same provider as the Named Credential. Keeping a second Named Credential set up and tested means you can switch within minutes if your main provider has an outage. Test it again after every key rotation.

Troubleshooting#

"AI provider returned an error. Please try again or contact your administrator." Users see this when the provider rejects the request, for example with 401 Unauthorized because the key is wrong, expired or revoked. Check the header value on the External Credential, and that the key is still active in your provider account.

"AI provider access is not configured for your user." The user cannot use the credential. Check that one of their permission sets grants principal access, and that they have Read access to User External Credentials.

"AI provider is not configured." The Named Credential name in the Org Profile does not match the one in Setup exactly (it is case-sensitive), the credential does not exist, or CloudConnected is missing from Allowed Namespaces for Callouts on it.