Registering a private app
Private apps, aka internal apps, enable you to share your integration with any user/company in Pipedrive via a direct, unlisted installation link. To do so, you must fill out the parts of the app registration form that cover app creation and make your private app live.
How to find Developer Hub
First, go to Settings by clicking on your profile name in the upper right corner of the top navigation bar. Find the company name of your sandbox account and choose Developer Hub from the drop-down menu:
You must have a developer sandbox account for app creation to see Developer Hub.
Register a new private app
To register a new app, click on the green “Create an app” button (or “+ Create an app” if you have existing apps) followed by “Create private app”. This is also where you’d see a list of your public and private apps if you have any.
App registration form
The app registration form for private apps contains three different tabs.
You can save your app anytime by clicking the green “Save” button and exiting the form by clicking the white “Close app settings” button. This will take you back to your Developer Hub dashboard.
Read on to find out how and what to fill in each tab.
Basic info
This tab has two required fields – App name and OAuth Callback URL. Once you’ve filled this in, click the green “Save” button to save the form. You’ll then be brought to the second tab, “OAuth & access scopes”, where you’ll get your client_id and client_secret and the option to make your app live via the “Change to live” button.
| Field | Description |
|---|---|
| App name (required) | Insert your app’s name by what it’s going to be recognized by in the Marketplace. Example: Car Services App |
| Callback URL (required, one URL per app) | Insert a link where an authorization code will be sent if the user approves or declines the installation of your app. This link is also where we return the user after successful authentication. Technically, a callback URL is the same thing as an OAuth redirect_uri.It’s okay to insert a non-functioning URL when creating a new app as long as you can update this field with a proper URL after implementing the logic needed to accept user authorization in your code. Please keep in mind that we allow only one callback URL per app. Example: https://www.carservicesapp.com/API/v2/callback |
OAuth & Access scopes
| Field | Description |
|---|---|
| Access scopes (required) | Using scopes, you can specify precisely what data access your application needs. Your selection will depend significantly on the endpoints you use in your app.You can also select the respective scope in this section if you are building a manifest-based app extension. Example:  Read users data See recent account activity |
| Installation URL | This is where you can add an optional OAuth authorization link with the state parameter. Find out more about the state parameter here. |
| Client ID | This is where you will get your app’s unique client_id and client_secret for OAuth authorization. |
Once you’ve completed filling up the Basic info and OAuth & access scopes, we advise you to start installing your app and testing it to see how it works. You can do so by clicking on the green “Install & test” button in the bottom left of the tab.
App extensions
App extensions let you extend Pipedrive’s user interface with your app’s functionality and content to let users do more in one place. Find out more about them here.
Within Developer Hub, the App extensions tab is where you can add new app extensions and manage the ones you’ve added before. A modal with an app extension creation form will open when you click the button to add the respective app extension.
You can also make your app live via the “Change to live” button in this tab.
Link actions
Learn more here.
| Field | Description |
|---|---|
| Action name (required) | Insert your app action’s name that will be displayed in the Pipedrive UI. The name should be short, descriptive of the app action, and be in a sentence case format.Example: Send quote - Car Services |
| Action description | To showcase the interactive features of your app, your action’s name and description will appear in the Features section of your Marketplace app listing. Use the description field to let users know what they can do with this action. Optional; max 150 characters. |
| URL link (required) | Add the URL that will redirect the user to the correct app page when an action is clicked. The URL must handle both scenarios of the user being logged into your app and not being logged in. Example: https://www.carservicesapp.com/handle_action |
| JWT secret | If left empty, client_secret will be used by default. |
| Locations (one required) | Specify in which views the app action will be displayed. There can be a maximum of 3 app actions per app or custom modals in one view, altogether 21 (7 different views x 3 actions per view). Example: Activities list Person details |
JSON modals
Learn more here.
| Field | Description |
|---|---|
| Action name (required) | The name of the JSON modal. The name should be short (max 30 characters), actionable, and sentence-cased (only capitalize the first word). Example: + Prod. details - Car Services |
| Action description | To showcase the interactive features of your app, your action’s name and description will appear in the Features section of your Marketplace app listing. Use the description field to let users know what they can do with this action. Optional; max 150 characters. |
| API endpoint (required) | All API requests related to this action will be sent to this URL. Example: https://www.carservicesapp.com/handle_action |
| JWT secret | If left empty, client_secret will be used by default. |
| JSON schema (required) | The JSON schema for your JSON modal. |
| Locations (one required) | There can be a maximum of 3 app actions or custom modals per location. Each app can have a total of 21 app actions. See more about available locations in app actions' visibility. Example: Deal details |
JSON panels
Learn more here.
| Field | Description |
|---|---|
| Panel name (required) | Insert your JSON panel’s name that will be displayed in the Pipedrive UI. The JSON panel’s name should be descriptive and have a maximum of 30 characters. Example: Car PM – Car Services |
| Panel description | To showcase the interactive features of your app, your panel’s name and description will appear in the Features section of your Marketplace app listing. Use the description field to let users know what they can do within this panel. Optional; max 150 characters. |
| API Endpoint (required) | The URL of the endpoint which we'll use to fetch the data of the object properties Example: www.api.pipedrive.com/deal-view/visits |
| HTTP Auth username (required) and HTTP Auth password (required) | Our service will send the HTTP request with these credentials as the Basic Authentication header to protect your data. To protect your data, we strongly recommend using authenticated HTTPS requests. Note that we do not support self-signed certificates. |
| JWT secret | JWT is required if HTTP Auth is not provided. |
| JSON data structure (required) | A JSON file that describes the structure of your JSON panel as seen in the Pipedrive UI. See here for more information. |
| Panel locations (one required) | Choose where the panel will be displayed: – Deal details – Person details – Organization details Each app can have one JSON or custom panel in each location. |
Custom modals
Learn more here.
| Field | Description |
|---|---|
| Modal name (required) | The name of your custom modal. Descriptive, max 30 characters and should be sentence-cased (only capitalize the first word). |
| Modal description | To showcase the interactive features of your app, your modal’s name and description will appear in the Features section of your Marketplace app listing. Use the description field to let users know what they can do within this modal. Optional; max 150 characters. |
| Iframe URL (required) | URL of the web content to be shown within the iframe – Please ensure your iframe URL uses HTTPS |
| JWT secret | Optional. Defaults to client secret |
| Entry points | The custom modal will be shown as a link in the actions menu of the chosen entry point(s). Choose the location(s) your custom modal can be triggered from: – Activities list – Deal details – Deals list – Person details – People list – Organization details – Organizations list If no entry points are selected, the only way to open a modal is via the SDK. Maximum 3 app extensions per location. Each app can have a total of 21 custom modals or app actions. |
Custom panels
Learn more here.
| Field | Description |
|---|---|
| Panel name (required) | The name of your custom panel. Descriptive, max 30 characters and should be sentence-cased (only capitalize the first word). |
| Panel description | To showcase the interactive features of your app, your modal’s name and description will appear in the Features section of your Marketplace app listing. Use the description field to let users know what they can do within this panl. Optional; max 150 characters. |
| Iframe URL (required) | URL of the web content to be shown within the iframe – Please ensure your iframe URL uses HTTPS |
| JWT secret | Optional. Defaults to client secret |
| Panel locations (one required) | Choose where the custom panel will be displayed: – Deals details view – People details view – Organizations details view Each app can have one custom or JSON panel in each location. |
App settings page
Learn more here.
| Field | Description |
|---|---|
| Type | Choose how you want your app’s user to access their app settings – External link – Custom UI |
| URL (required) – for external link | Add the URL that will redirect the user to your app settings page |
| Iframe URL (required) – for ustom UI | URL of the web content to be shown within the iframe – Please ensure your iframe URL uses HTTPS |
| JWT Secret – for Custom UI | Optional. Defaults toclient secret. |
Do install and test your app after you add app extensions to see how it works for your users.
How to share your private app
You have to make your private app live before you can share it. You can do this by clicking the “Change to live” button in the app registration form.
For new private apps
After you fill in your app name and callback URL in the Basic info tab and click “Save”, you will be brought to the OAuth & access scopes with the “Change to live” button enabled. Once the “Change to live” button is enabled, you can make your private app live anytime by clicking on it in any tab.
For draft private apps
The “Change to live” button will be enabled when you open your draft private app, as you’ve previously filled in and saved your app name and callback URL. You can make your private app live anytime by clicking “Change to live” in any tab.
As we will validate your callback URL when you click “Change to live”, please ensure your OAuth callback URL is a functioning one.
Note that live private apps cannot be reverted back to draft status. Any changes you make to your live private app will be immediately available for all users once you click ‘Save’.
All live private apps will have a green callout box at the top of the app registration form to indicate that they are live. Private apps that are not live will only be able to be used within the same company.
Updated 5 days ago