Salesforce

Overview

Birdie’s Salesforce connector lets you import key Salesforce entities (such as cases, emails, and accounts) into Birdie so you can centralize customer support and account data alongside other feedback sources.

Requirements

Birdie can authenticate to Salesforce using one of these flows. Which one you use depends on your IT/security policies.

• Client credentials flow

• Refresh token flow (recommended)

• Username-password flow

Each flow requires a Salesforce domain and the connected app Client ID (consumer key) and Client Secret (consumer secret). The Refresh Token and Username-Password flows additionally require user-specific values.

Relevant Salesforce documentation:

• Client credentials flow: https://help.salesforce.com/s/articleView?language=en_US&id=sf.remoteaccess_oauth_client_credentials_flow.htm&type=5

• Refresh token flow: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_refresh_token_flow.htm&type=5

• Username-password flow: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_username_password_flow.htm&type=5

Minimum required values by flow:

• Client credentials flow

  • Domain: e.g. {DOMAIN}.salesforce.com

  • Client ID (consumer key)

  • Client Secret (consumer secret)

• Refresh token flow

  • Domain: e.g. {DOMAIN}.salesforce.com

  • Client ID (consumer key)

  • Client Secret (consumer secret)

  • Refresh Token

• Username-password flow

  • Domain: e.g. {DOMAIN}.salesforce.com

  • Client ID (consumer key)

  • Client Secret (consumer secret)

  • User (username)

  • Password

We recommend following the setup steps for the Refresh Token Flow.

Setup in Salesforce

To set up your Salesforce integration, you must configure a connected app in Salesforce. For the official Salesforce docs on connected apps, see: https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm&type=5

1

Create a Connected App (Admin)

1. Log into Salesforce as an administrator.

2. Open Setup (Gear icon).

3. In the left pane go to: Platform Tools > Apps > App Manager.

4. Click "New Connected App" (upper right).

5. On the new connected app page, fill in the required Basic Information:

   • Connected App Name: Birdie Integration

   • API Name: Birdie_Integration

   • Contact Email: [email protected]

6. Scroll to "API (Enable OAuth Settings)" and select "Enable OAuth Settings". Fill in:

   • Callback URL: https://login.salesforce.com/

   • OAuth Scopes (select):

     • Manage user data via APIs (api)

     • Manage user data via Web browsers (web)

     • Perform requests at any time (refresh_token, offline_access)

   • Uncheck "Require Proof Key for Code Exchange (PCKE) Extension for Supported Authorization Flows"

   • (Optional) Check "Enable Client Credentials flow" (only if you want the client credentials flow)

7. Click Save.

8. After saving you will be redirected to the View page for your connected app.

2

Manage Connected App Policies

1. From Platform Tools > Apps > App Manager find your connected app and open Dropdown > View (or use the View page after creation).

2. Click "Edit Policies".

3. Recommended configurations to review:

   • Permitted Users: All users may self-authorize

   • IP Relaxation: Relax IP restrictions (Optional — only if your org uses IP enforcement)

   • Refresh token policy: Refresh token is valid until revoked (Optional — avoids frequently regenerating refresh tokens)

   • Client Credentials Flow - Run as: Select a user that has API permissions and access to the connected app (Optional — required only for client credentials flow)

4. Save policy changes.

3

Retrieve Client ID and Client Secret

1. From the connected app View page click "Manage Consumer Details".

2. Copy the Consumer Key and Consumer Secret — these are the Client ID and Client Secret that Birdie needs.

3. If using the Client Credentials flow, send the Domain, Client ID, and Client Secret to the Birdie team.

Connect to Birdie

If you are using the Client Credentials flow, share the Domain, Client ID, and Client Secret securely with the Birdie team.

If you are using the Refresh Token or Username-Password flows, follow the steps below to generate and share the additional required values.

Generating a Refresh Token (recommended)

If you opted to authenticate via a refresh token, follow these steps to generate and capture the refresh token.

1

Build Authorization URL and Authorize

1. Construct the authorization URL using this template:

https://{DOMAIN}.my.salesforce.com/services/oauth2/authorize?client_id={CLIENT_ID}&redirect_uri=https%3A%2F%2Flogin.salesforce.com&response_type=code

Example (if domain is birdie and client id is 1234):

https://birdie.my.salesforce.com/services/oauth2/authorize?client_id=1234&redirect_uri=https%3A%2F%2Flogin.salesforce.com&response_type=code

1. Open the URL in your web browser and authorize the Birdie connected app.

2. After authorizing you'll be redirected to the Salesforce login page. The browser URL will contain the authorization code in this pattern:

https://login.salesforce.com/?code={CODE}

1. Copy the {CODE} value from the URL — you'll use it in the next step.

2

Exchange Authorization Code for Tokens

Use this curl command to exchange the authorization code for access and refresh tokens:

curl -X POST 'https://{DOMAIN}.my.salesforce.com/services/oauth2/token?code={CODE}&grant_type=authorization_code&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&redirect_uri=https%3A%2F%2Flogin.salesforce.com'

This returns JSON similar to:

{
  "access_token":"123",
  "refresh_token":"456",
  "signature":"789",
  "scope":"refresh_token web api full",
  "id_token":"...",
  "instance_url":"https://{DOMAIN}.my.salesforce.com",
  "id":"https://login.salesforce.com/...",
  "token_type":"Bearer",
  "issued_at":"1726008721576"
}

Save the refresh_token value and send it (along with Client ID, Client Secret, and Domain) to the Birdie team.

Notes and recommendations

• Use the Refresh Token flow when possible — it avoids configuring a user for Birdie and simplifies token renewal.

• If you choose Client Credentials flow, ensure the selected "Run as" user has API and connected app access.

• Keep Client Secret and Refresh Token secure — treat them as sensitive credentials.

If you need help, provide Birdie the Domain, Client ID, Client Secret, and (if using refresh token flow) the Refresh Token.

Data in scope

This integration can import the following data from your Salesforce account:

• Case: Represents a case, which is a customer issue or problem.

• CaseComment: Represents a comment that provides additional information about the associated Case.

• EmailMessage: Represents an email in Salesforce.

• Account: Represents an individual account, which is an organization or person involved with your business (such as customers, competitors, and partners).