Salesforce Integration - Required User Permissions
This guide is for Salesforce administrators. It describes the Salesforce permissions the connecting user must have for CrankWheel’s direct Salesforce integration to work.
The integration acts entirely as the user who authorizes the connection — it can only see and do what that user is allowed to do. There is no separate service account.
OAuth scopes (Connected App)
The CrankWheel Connected App requests only two OAuth scopes. These are capability scopes — they govern how the app talks to Salesforce, not which records it can access:
- Manage user data via APIs (
api) — use of the Salesforce REST API as the connected user. - Perform requests at any time (
refresh_token,offline_access) — long-lived access via a refresh token.
Which records and fields can actually be read or written is governed entirely by the user’s Profile, Permission Sets, Field-Level Security, and sharing rules — described below.
What the integration does in Salesforce
| Operation | Object | Access needed |
|---|---|---|
| Look up the agent by email | User | Read |
| Create the meeting Event on session start | Event (Activity) | Create |
| Update the Event (subject / description / times) on session end and when a recording is attached | Event | Edit + Read |
| Read Contact for the screen-pop; query Contacts under an Account | Contact | Read |
| Read Lead for the screen-pop | Lead | Read |
| Read Account (including Person Accounts) | Account | Read |
| Read Opportunity (to find its parent Account) | Opportunity | Read |
Required permissions (Profile or Permission Set)
1. System permissions
- API Enabled — required. Without this, the OAuth
apiscope is useless and nothing works. - Approve Uninstalled Connected Apps — required to authorize the connection (see the note below).
- Edit Events — required to create and update meeting Events (see “Activities / Events” below).
Note: Most standard profiles include API Enabled, but some Salesforce license types do not. This is the most common cause of a failed integration.
“App must be installed into org” / OAuth approval error? The CrankWheel Connected App is defined in CrankWheel’s own Salesforce org, so to your org it is an uninstalled (remote) app. Salesforce only lets a user authorize an uninstalled app if either the app is installed org-wide, or the user has the Approve Uninstalled Connected Apps system permission. A recent Salesforce enforcement change means connections that worked before may now fail with OAUTH_APPROVAL_ERROR_GENERIC or invalid_client / app must be installed into org — granting this permission (or installing the app via Setup → Connected Apps OAuth Usage → Install) resolves it. Administrators usually satisfy this check automatically, so the error often appears only for non-admin users. Note: the legacy Offline User profile permission is unrelated and does not need to be enabled.
2. Object permissions (CRUD)
- Contacts: Read
- Leads: Read
- Accounts: Read
- Opportunities: Read
- Users: Read (to resolve the agent’s email to a Salesforce user; normally granted by default)
Activities / Events: Salesforce Activities (Events and Tasks) do not have object-level Create/Read/Edit/Delete settings. Instead, the ability to create, edit and delete Events is granted by the Edit Events system permission (listed in section 1 above), not on an “Event” object. This is the only write access the integration needs.
3. Field-Level Security (Read)
If the org uses restrictive field-level security, these specific fields must be readable by the user:
- Contact / Lead:
Name,Email,Phone,MobilePhone,HomePhone - Account (Person Accounts):
PersonEmail,PersonMobilePhone,PersonHomePhone,PersonOtherPhone - Opportunity:
AccountId - Event:
Subject,Description,StartDateTime,EndDateTime,OwnerId,Location,WhoId,WhatId
Note: If you have worked with us to customize the CrankWheel field mapping, any additional custom fields that were re-mapped also need read access.
4. Record visibility (sharing)
Object and field permissions are not enough on their own — the user must also be able to see the specific records involved, via record ownership, role hierarchy, or sharing rules. The screen-pop and event linking work from record IDs; if a record is outside the user’s sharing scope, the lookup simply returns nothing, even when all object and field permissions are correct.
Testing with a Salesforce sandbox
Testing the integration against a Salesforce sandbox is available. To enable it, contact our support team at support@crankwheel.com and request that your account be switched to Salesforce sandbox testing. Once that is done, the integration will authorize against your sandbox rather than your production org.
Two things worth flagging
- All access runs as the authorizing user, not a service account. The integration can only see and do what that one user can. Please authorize with a user whose profile and sharing cover all needed records.
- Events created by the integration are owned by the agent, resolved by matching their CrankWheel email to a Salesforce User email. If no active Salesforce user matches that email, ownership falls back to the connecting (admin) user. Make sure each agent’s CrankWheel email matches their Salesforce User email.
If you would like help setting this up, contact support@crankwheel.com.