Connecting to Salesforce

In order to access your Salesforce metadata you need to connect (via OAuth) to one or more Salesforce orgs.

tip

You can manage orgs both in your personal account, as well as (separately) for each team that you are a member of.

Connecting to a new Salesforce org

To add a new org, navigate to https://app.cirra.ai/. If this is a new account, you should see a page like this:

Click the Add Organization button. In the dialog that appears, select the Environment type, optionally enter a custom domain, and click Connect.

After entering your Salesforce login credentials you will be asked to authorize access to your org:

Note that we only ask for the minimum permissions required to manage your Salesforce org via the API. The OAuth credentials requested cannot be used to log into the Salesforce UI, only for access via API.

Clicking Allow should show a confirmation as follows:

warning

If you receive an OAuth approval error after authorizing access, see Troubleshooting OAuth approvals below.

If the authorization flow was succesful, the new org should appear:

info

Cirra AI will act under the permissions of the user who granted the OAuth permissions, so it will only be able to make changes that the user would be able to make manually in the Setup UI.

See below under Access rights and security for more details.

Selecting the active org

The MCP server can only interact with one org at a time. The default active org is indicated by:

• a green border if it has a valid OAuth connection

  

• an orange or red border if the OAuth has expired or is invalid

  

  If the OAuth is not valid you should click the Reauthorize or Reconnect button to attempt to refresh it.

To change the active org, click the Select or Reauthorize button for the desired org.

Note that you can also switch the target org using the MCP server as explained in Switching between Salesforce orgs

Managing orgs

You can use the icons at the top right of each organization card to:

• Manage the access rights settings for the org (see below)
• Remove the org connection
• Open the org (login may be required)

Access rights and security

It is critically important to carefully control access to your enterprise (meta)data. Cirra AI and Salesforce together provide multiple layers of protection:

• All access to Cirra AI is through OAuth with a Connected App
  • No need to share your Salesforce user credentials with Cirra AI
  • Cirra AI's access to your Salesforce org is limited to that of the user you used to establish the OAuth connection.
  • The OAuth user can be an API only user. In any case select a user with only the minimum required access.
• Salesforce provides numerous tools to control who has access to Connected Apps
  • See the Best Practices section below
• Cirra AI allows you to further limit the access granted to orgs, or categories of orgs, to avoid exposing confidential information
  • See Cirra AI org-level access controls

Also:

• Cirra AI does not store any (meta)data or train models on it
• You can select an LLM provider that provides acceptable data privacy assurances
  • Leading providers allow you to (at least) opt out of sharing your data for training purposes
• AI clients typically allow you to require approval before sensitive tools are called

Connected App best practices

Salesforce limits the ability to install Connected Apps for certain users and orgs. See https://help.salesforce.com/s/articleView?id=005132365&type=1 for details.

To control which users can install the app and streamline authorization for legitimate users, we recommend that a System Administrator explicitly installs our Connected App before it is made available to users, as follows.

• Connect the Salesforce org to Cirra AI and authorize it using OAuth

  Please see below for troubleshooting steps if you have issues authorizing the app

• Explicitly install the Cirra AI Connected App

  In Salesforce Setup, go to Connected Apps OAuth Usage, locate the Cirra AI app, and click Load Actions followed by Install

  

• Optionally, restrict access to the app to selected users

  • Click Edit Policies on the Connected App detail screen
    • Or if you no longer have the detail screen open, return to the Connected Apps OAuth Usage list and click Load Actions followed by Manage App Policies
  • Set the OAuth policy to Admin approved users are pre-authorized
  • Assign permission to use the app to specific users

    • Most explicit is to create and assign a dedicated Cirra AI permission set (the set can be empty -- it's just used for this one purpose).

      But you can use existing permission sets too

    • Assign the permission set(s) to any user who needs access

  • Add the permission set(s) to the list on the Connected App Detail screen
  • Users who do not have the required permission set will not be able to connect to the org from inside Cirra AI

For full details on Connected App access controls, see the Salesforce documentation here

Using a dedicated API Integration user

Instead of connecting with a Salesforce user with a full license, you can use a free Salesforce Integration user to connect Cirra AI to your org. This avoids tying the connection to a named user's account, without adding the cost of a paid license.

info

Note that anyone connecting with the API user credentials will be working under

To set this up:

1. Connect Cirra AI with a System Administrator first — this creates the Connected App in your org
2. Install the Connected App — even though the app exists in the org, it must be explicitly installed for API-only users to connect. Follow the installation steps above
3. Create an integration user with the following settings:
   • License: Salesforce Integration
   • Profile: Minimum Access - API Only Integrations
4. Assign the Salesforce API Integration Permission Set License to the user
5. Create a permission set with all the permissions you want to grant this user, and assign it to the user
6. Use the integration user to connect Cirra AI to the org (add a new connection via OAuth)
7. Remove the original admin connection — you can now safely delete the connection that used your admin user

tip

This setup is typically only needed for production orgs. In sandbox orgs you can simply use regular users.

Cirra AI org-level access controls

On top of the security and control provided by OAuth and Salesforce, you can further limit the level of access to (meta)data in an org or category of orgs.

Access levels can be separately set for four categories of (meta)data:

• Metadata: all configuration, such as objects, fields, layouts, permission sets, profiles etc.
• User Data: users, groups, queues etc.
• Personal Setup Data: setup controlled by individual users, such as reports and email templates
• Business Data: Leads, Accounts, Cases etc.

For each of these access can be set at three levels:

• None: (meta)data can neither be read nor modified
• Read Only: (meta)data can be read, but not modified
• Read and Write: full access

Access can be restricted at two levels:

• The category of Salesforce orgs: production, sandbox, developer or scratch
• Each individual org

To configure these settings, click on the settings icon. This is available for each org category (Production, Sandbox etc) as well as the card for each individual org.

By default, individual org level settings can only be set to be more restrictive than category level settings. Less restrictive settings are disabled.

However, if you select the Allow override? option then individual orgs can relax the category-level settings

For Team accounts, category levels can only be set by owners or admins of the team.

To summarize, a user will have access to (meta)data in an org only if all of the following are true:

• The user who connected the org (via OAuth) has access
• The org category settings allow access
  • Unless Allow override? is enabled
• The individual org settings allow access

Troubleshooting OAuth approvals

If you receive an error when authorizing a connection to your org it is most likely due to various Salesforce security mechanisms.

The most common issues are shown below.

If you continue to face problems, please contact us for support.

OAUTH_APPROVAL_ERROR_GENERIC

If you receive an OAUTH_APPROVAL_ERROR_GENERIC error (with app+must+be+installed+into+org visible in the browser URL) this is most likely because you do not have permission to install Connected Apps.

To resolve this you can ask your System Administrator to either:

• Grant you the Approve Uninstalled Connected Apps permission
  • Either by adding that permission to an existing permission set assigned to you, or by creating a new permission set with that permission added
• Install and approve the Cirra AI connected app, in two steps:
  1. First connect the org from Cirra AI as an admin with the Approve Uninstalled Connected Apps permission — this installs the connected app into the org.
  2. Then explicitly approve the app in Salesforce Setup under Connected Apps OAuth Usage by clicking Install.
  

For more detail on the "Approve Uninstalled Connected Apps" user permission and installing Connected Apps see: https://help.salesforce.com/s/articleView?id=005132365&type=1

You can also refer to the Connected App best practices section above for our recommendations on configuring the Cirra AI Connected App.

Authorization Failed: invalid_grant

Some orgs restrict logins to a set of trusted IP addresses by configuring login IP ranges on the profile of the connecting user. This is a common security hardening which also applies to API and OAuth logins.

Because Cirra AI connects to your org from its own servers, Salesforce blocks the connection with an ip restricted error unless Cirra AI's IP address is on the allowlist.

To allow access, a System Administrator should add the Cirra AI outbound IP addresses to the Login IP Ranges of the profile assigned to the user used to connect Cirra AI:

1. In Salesforce Setup, enter Profiles in the Quick Find box, then select Profiles.

2. Open the profile of the Salesforce user you use to connect Cirra AI.

3. In the Login IP Ranges section, click New (or Add IP Ranges in the Enhanced Profile User Interface).

4. Add two new IP ranges, one for each of the following addresses: 104.46.202.129 and 20.72.202.165.

   Each address is a separate single-address range with the address set as both the IP Start Address and IP End Address. Optionally set the description to Cirra AI.

   

5. Click Save.

Then return to Cirra AI and click Reauthorize on the org (or add the org again). The connection should now succeed.

info

These addresses are static under normal operation and we will notify customers if they change. You can also return here for an updated list if reauthorization starts failing with an ip restricted error.

For Salesforce's documentation on this feature, see Restrict Login IP Addresses in Profiles.