# Salesforce

SureCloud connects to Salesforce to retrieve user and profile data, permission set assignments, field-level security configuration, and audit log records. This allows SureCloud to verify that access to customer data within Salesforce is controlled by the principle of least privilege, that data loss prevention policies are in place, and that login and administrative activity is being logged and retained.

## Authentication and setup

Salesforce supports OAuth 2.0 with the JWT Bearer flow for server-to-server integrations. SureCloud uses a Connected App with a certificate-based JWT grant for secure, user-independent access.

{% stepper %}
{% step %}

### Create a Connected App in Salesforce

Log in to Salesforce with a System Administrator account. Navigate to **Setup → Apps → App Manager** and click **New Connected App**. Name it `SureCloud CCM`. Enable **OAuth Settings** and set the **Callback URL** to `https://login.salesforce.com/services/oauth2/callback`. Add the required OAuth scopes (see below). Enable **Use Digital Signatures** and upload a public certificate (SureCloud will provide the public key for this step — contact SureCloud Support to obtain it). Click **Save**.
{% endstep %}

{% step %}

### Approve the Connected App policies

Navigate to **Setup → Apps → Connected Apps → Manage Connected Apps**, find the SureCloud CCM app, and click **Edit**. Set **Permitted Users** to **Admin approved users are pre-authorized** and click **Save**.
{% endstep %}

{% step %}

### Note your Connected App credentials

From the Connected App detail page, copy the **Consumer Key** (Client ID). Note your Salesforce organisation's **Login URL** (e.g. `https://login.salesforce.com` for production, or your custom domain).
{% endstep %}

{% step %}

### Enter the credentials in SureCloud

Navigate to **SureCloud → Integrations → Salesforce → Connect**. Enter your Salesforce login URL, the Connected App Consumer Key, and the username of a Salesforce system user that will be used for JWT subject claims. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
SureCloud uses the JWT Bearer flow for Salesforce. No user password is stored — authentication is performed using a certificate key pair managed by SureCloud. Access tokens are short-lived and obtained automatically at each polling cycle.
{% endhint %}

## Endpoints

| API Call                                                                    | Use Case                                                      |
| --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `GET /services/data/v58.0/query/?q=SELECT+Id,Name,IsActive+FROM+User`       | Enumerate all Salesforce users and their active status        |
| `GET /services/data/v58.0/query/?q=SELECT+...+FROM+Profile`                 | Retrieve user profiles and their associated permissions       |
| `GET /services/data/v58.0/query/?q=SELECT+...+FROM+PermissionSet`           | Retrieve permission sets and their assignees                  |
| `GET /services/data/v58.0/query/?q=SELECT+...+FROM+PermissionSetAssignment` | Map permission set assignments to users                       |
| `GET /services/data/v58.0/query/?q=SELECT+...+FROM+LoginHistory`            | Retrieve login history for audit and access evidence          |
| `GET /services/data/v58.0/query/?q=SELECT+...+FROM+SetupAuditTrail`         | Retrieve administrative change audit trail records            |
| `GET /services/data/v58.0/limits`                                           | Retrieve API usage and org-level limits for health monitoring |

## Pagination

Salesforce SOQL query results use `nextRecordsUrl` pagination. SureCloud follows the `nextRecordsUrl` returned in each query response to retrieve subsequent batches, continuing until no `nextRecordsUrl` is present.

```
GET /services/data/v58.0/query/01g...
```

Each response includes a `nextRecordsUrl` path if more records exist. SureCloud follows this path directly until the final page is reached.

## Required permissions

SureCloud requires a Salesforce system user with the following profile permissions or a custom permission set:

| Permission                                    | Purpose                                               |
| --------------------------------------------- | ----------------------------------------------------- |
| View All Users                                | Enumerate all user accounts and profiles              |
| View Setup and Configuration                  | Read permission sets, profiles, and org configuration |
| Manage Users (read-only equivalent via query) | Access PermissionSetAssignment records                |
| View All Data                                 | Access LoginHistory and SetupAuditTrail via SOQL      |
| API Enabled                                   | Required for all REST API access                      |

## Polling frequency

| Data Type                            | Interval       |
| ------------------------------------ | -------------- |
| Users, profiles, and permission sets | Every 24 hours |
| Permission set assignments           | Every 24 hours |
| Login history                        | Every 6 hours  |
| Setup audit trail                    | Every 6 hours  |

## Troubleshooting

<details>

<summary>JWT authentication fails with "invalid_grant"</summary>

This typically occurs when the Connected App's digital signature certificate does not match the key pair held by SureCloud, or when the system user's account is inactive or locked. Verify the Connected App is active, the correct public certificate is uploaded, and the system user account is active in **Setup → Users**. Contact SureCloud Support to verify the JWT key configuration.

</details>

<details>

<summary>SOQL queries return "INSUFFICIENT_ACCESS_OR_READONLY"</summary>

The system user profile does not have the required permissions for the queried object. Review the required permissions above and update the profile or permission set assigned to the SureCloud system user in **Setup → Profiles** or **Setup → Permission Sets**.

</details>

<details>

<summary>SetupAuditTrail returns limited data</summary>

Salesforce retains SetupAuditTrail records for 180 days. SureCloud collects within this window. For audit requirements beyond 180 days, Salesforce audit data must be exported and retained externally before the retention window expires.

</details>

<details>

<summary>Login URL is incorrect for sandbox or custom domain</summary>

Production Salesforce orgs use `https://login.salesforce.com`. Sandbox orgs use `https://test.salesforce.com`. Orgs with custom domains use `https://<mydomain>.my.salesforce.com`. Ensure the correct login URL is configured in **SureCloud → Integrations → Salesforce → Edit Connection**.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/salesforce.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.