How to get your OAuth 2 credentials in PipeDrive

August 26, 2024

This guide explains how to create a public developer app in Pipedrive and obtain your OAuth 2 credentials. You'll need these credentials in order to authenticate your app with Unified.to.

Note: The state parameter is not automatically available in Marketplace Manager. To enable it for your app, please write to marketplace.devs@pipedrive.com.

Before you begin

Before you create a developer app in Pipedrive, ensure:

• You have a Pipedrive developer sandbox account. If you don't have one, sign up at Pipedrive's developer portal.

Access the Developer Hub

1. Log in to your Pipedrive account.
2. Click on your profile name in the upper right corner of the top navigation bar.
3. Select Developer Hub from the drop-down menu.
   

Create a Pipedrive public app

1. Click Create an app (or "+ Create an app" if you have existing apps).
2. Select Create public app.
3. Fill in your app details under Basic info.
   1. In the Callback URL field, choose based on your flow:
   • Unified-hosted OAuth: https://api.unified.to/oauth/code
   • Pipedrive Marketplace (own install + uninstall): your app callback URL. Marketplace requires one callback that handles OAuth install (GET) and uninstall (DELETE). Unified's callback cannot receive uninstall.
   
   
4. Click Save. You will be redirected to the OAuth & access scopes page after your app is created.

Configure scopes and get your OAuth 2 credentials

1. Select the scopes your app requires. Only choose scopes that are necessary for your app's functionality.
   1. For example, if you want to be notified about new or updated deals from Pipedrive, select Deals and choose whether you need read-only access or full (i.e. create, update, read, delete) access.
2. Scroll down to the Client ID section.
3. Here you'll find your client_id and client_secret. Make a note of them as you will need it for the final step.
4. Click Save.

Activate the Pipedrive integration in Unified.to with your client ID and secret

1. Open a new tab and navigate to the Pipedrive integration in Unified.to.
2. You will need the following two pieces of information from the earlier steps:
   1. Client ID
   2. Client secret
3. Copy and paste these values into their respective fields on the page. Make sure that OAuth 2 is selected under Authentication Method.
4. Click Activate.

Marketplace listing: BYO callback → import into Unified

If you list on the Pipedrive Marketplace and must own the callback URL for install and uninstall:

1. Set Callback URL to your app (not Unified).
2. Activate Pipedrive in Unified with the same client_id / client_secret from this Marketplace app.
3. On install, exchange the code on your server for access_token, refresh_token, and api_domain.
4. Create the Unified connection with POST /unified/connection using the payload below. Set auth.api_url to the company host from Pipedrive's api_domain token field. Do not send auth.api_domain (rejected by connection validation) or other_auth_info on this OAuth import.
5. On uninstall (Pipedrive sends DELETE to your callback), revoke the refresh token at Pipedrive (POST https://oauth.pipedrive.com/oauth/revoke), then call DELETE /unified/connection/{id} in Unified.

Full import shape (adjust permissions to match your scopes; set api_url to Pipedrive's token-response api_domain value — do not send api_domain as a connection field):

{
  "integration_type": "pipedrive",
  "categories": ["crm"],
  "permissions": [
    "crm_deal_read",
    "crm_deal_write",
    "crm_contact_read",
    "crm_contact_write"
  ],
  "environment": "Production",
  "external_xref": "<your-end-customer-id>",
  "auth": {
    "access_token": "<from Pipedrive token response>",
    "refresh_token": "<from Pipedrive token response>",
    "expires_in": 3599,
    "api_url": "https://acme.pipedrive.com"
  }
}

Use the same Marketplace client_id / client_secret when activating Pipedrive in Unified so token refresh works. General import guidance: How to migrate or import your integrations into Unified.to.

Notes:

• One Marketplace app = one callback URL. You cannot point the same app at both Zig/your domain and https://api.unified.to/oauth/code. For Marketplace production, use your callback + import. If you still want Unified-hosted OAuth (e.g. internal testing), use a separate private/sandbox Pipedrive app with Unified's redirect.
• Refresh works on imported connections when Unified's Pipedrive activation uses the same Marketplace client_id / client_secret that issued the tokens. Include refresh_token and expires_in on import; do not send other_auth_info.