Connect your AI provider

AI Engine sends requests to your AI provider through a Salesforce Named Credential. Your API key is stored in an External Credential in your own org, and Salesforce adds it to each request. The key is not part of AI Engine's configuration and is not sent to Cloud Connected.

The setup has four parts:

1. An External Credential that holds your key.
2. A Named Credential with the provider URL.
3. Access to the credential for everyone who uses AI Engine.
4. The credential name in the AI Engine Org Profile.

Before you start#

• An API key from OpenAI or Anthropic, or an Azure OpenAI resource with a model deployment and its key.
• The AI Engine Admin and AI Engine User permission sets assigned to you. See Assign permission sets.

Step 1: Create the External Credential#

1. Go to Setup → Named Credentials, open the External Credentials tab and click New.
2. Enter a Label and Name, for example OpenAI, and set Authentication Protocol to Custom. Save.
3. Under Principals, click New. Enter a Parameter Name such as Default, keep Identity Type as Named Principal, and save.
4. Under Custom Headers, click New and add the header for your provider:

Replace YOUR_API_KEY with your key. For Authorization, keep the word Bearer and one space before the key. For Anthropic you do not need an anthropic-version header: AI Engine sends it with every Anthropic request itself.

Step 2: Create the Named Credential#

1. Go to Setup → Named Credentials, open the Named Credentials tab and click New.
2. Enter a Label and Name, for example OpenAI, Anthropic or AzureOpenAI. You will type this exact name into AI Engine later.
3. Set the URL:

4. Select the External Credential from step 1.
5. Make sure Enabled for Callouts is on.
6. In the Managed Package Callout Allowlist section, enter CloudConnected in Allowed Namespaces for Callouts. AI Engine runs in the CloudConnected namespace, and without this entry Salesforce does not let it use a credential you created.
7. Save.

Use only the base URL. AI Engine adds the path for each request itself.

Step 3: Give users access to the principal#

Every person who uses AI Engine, admins included, needs access to the principal from step 1. AI Engine User and AI Engine Admin come from a managed package, so your org may not let you edit them. The dependable way is a permission set of your own:

1. Go to Setup → Permission Sets and click New.
2. Enter a label such as AI Provider Access, leave License as --None--, and save.
3. Open External Credential Principal Access, click Edit, add the principal from step 1 (for example OpenAI - Default) and save.
4. Click Manage Assignments → Add Assignment, select every AI Engine user and admin, and assign.

Users also need the AI Engine User permission set, which includes the Read access to User External Credentials that Salesforce requires for the call. When you add AI Engine users later, assign them both permission sets.

Step 4: Link the credential in AI Engine#

AI Engine uses one Org Profile for the whole org. If a profile already exists, edit it rather than creating a second one.

1. Open the Ai Agent Admin Setup tab, go to Org Profile, and click + New Profile, or click the existing profile to edit it.
2. Select the AI Provider: OpenAI (Responses API), Azure OpenAI or Anthropic Claude. AI Engine fills in a suggested model and credential name.
3. In Named Credential, enter the exact name from step 2.
4. Choose the AI Model. For Azure OpenAI, type your deployment name, not the model family name.
5. Optionally choose a Fast model (internal steps) from the same provider. AI Engine uses it for web search steps, such as Web Check and Company News, and for answers in Help mode; everything else runs on the main model. Leave it on the provider default (for Azure OpenAI, leave it blank) if you are unsure.
6. Click Save.

Then run a first test.

Azure OpenAI#

• AI Engine calls your deployment at /openai/deployments/<deployment name>/chat/completions, so the AI Model field must match the deployment name exactly. Deployment names may contain only letters, digits, dots, hyphens and underscores.
• AI Engine's web search features use OpenAI's web search tool, which it does not call through Azure OpenAI. When Azure OpenAI is your provider, the features that search the web, such as Web Check and Company News, are sent to OpenAI instead, using the gpt-4.1-mini model, through a Named Credential that must be named exactly OpenAI. If you want those features, create an OpenAI External Credential and Named Credential as described above, with that name, and make sure your OpenAI key can use gpt-4.1-mini. If you do not, those features fail with an error and everything else keeps working. Take this into account if you chose Azure for data residency. See Choosing a provider for compliance.

Switching provider later#

You can switch provider at any time by creating credentials for the new provider and changing AI Provider, AI Model and Named Credential in the Org Profile. No reinstallation is needed. AI Engine does not switch providers automatically, but if you keep a second provider's credentials configured and tested, you can switch the Org Profile to it by hand if your main provider has an outage.

Troubleshooting#

To replace a key, see API keys and Named Credentials.