After registering the app, you have to add the necessary server-side logic to your app to establish the OAuth flow. Authorization via OAuth is a well-known and stable way to get fine-grained access to an API. Here's a diagram showing the flow of authorization:
And here's a video to get you more acquainted with building apps with OAuth:
This step is necessary to implement only when you allow app installation outside of the Marketplace.
First, your app must start the authorization process. For that you must direct the customer to the OAuth server’s /authorize endpoint:
GET https://oauth.pipedrive.com/oauth/authorize?client_id=b4d083d9216986345b32&state=148aHxbdd92&redirect_uri=https://awesomeapp.com/oauth/callback
The request must provide the following GET parameters:
client_id
Yes
The client ID provided to you by the Pipedrive Marketplace when you register your app.
redirect_uri
Yes
The callback URL you provided when you registered your app. Authorization code will be sent to that URL (if it matches with the value you entered in the registration form) if a user approves the app install. Or, if a customer declines, corresponding error will be sent to this URL as well.
state
No
You may pass any random string as the state parameter and the same string will be returned to your app after a user will authorize access. It may be used for storing user's session ID from your app or to distinguish different responses. Using state may increase security, see RFC-6749.
⚠️ The usage of the state parameter is unavailable when installing from the Pipedrive Marketplace. Please send a request to vendors@pipedrive.com to make it available for your app.
As a result of the request from Step 1, the customer will see a page with the confirmation dialogue which will present the details of your app (title, company name, icon) and will explain the permission scopes that you have set for the app. The customer should confirm one's wish to install the app by clicking "Allow and install" or denying authorization by clicking "Cancel".
After the customer accepts or denies your app installation, the browser will be redirected to your callback URL (which was registered with the app) with the result of the user's action:
GET https://<your_callback_url>?code=123.456.2d73391055ca60cbf07f13aaaaf1207cfe33a4b605&state=148aHxbdd92And the following query parameters will be passed to the request:
code
The authorization_code that was issued when the user agreed to the installation. You will need this code to exchange it for the access_token.
error
The error code (for example installation_denied) if the user denied installation.
Code and error parameters are mutually exclusive!
state
If state was provided during the authorization request, the same value will be returned to your callback URL.
After the customer has clicked "Allow and install" in Step 2, make sure that the customer has created and logged into an account in your app before exchanging the authorization_code.
After the customer has confirmed the app installation, you will need to exchange the authorization_code to a pair of access and refresh tokens. Using an access token, you can access the user's data.
Note that the authorization_code expires in 5 minutes.
In order to exchange the authorization_code for the tokens, you must execute this HTTP request to the OAuth server:
POST https://oauth.pipedrive.com/oauth/tokenContent-type for the request must be application/x-www-form-urlencoded.
In order to execute the request, your request has to be authenticated via HTTP Basic Auth with the values of the client_id and the client_secret (you can find the values like this).
Authorization
Base 64 encoded string containing the client_id and client_secret values. The value should be "Authorization: Basic <base64(client_id:client_secret)>".
Note that authentication could also be done by providing values for the client_id and the client_secret in the request body, but it's not recommended. Use it only when you cannot use HTTP Basic Auth approach.
grant_type
Since you are trying to exchange authorization code to a pair of tokens, you must use the value "authorization_code".
code
The authorization code that you received after user confirmed app installation.
redirect_uri
The callback URL you provided when you registered your app.
If all data is correct, you will receive a response with the JSON data:
access_token
You need to use an access token for accessing the user's data via API. access_token expires after 60 minutes (see Step 7 on how to refresh the token).
token_type
The format of the token. Always "bearer".
refresh_token
A refresh token is needed when you refresh the access token. refresh_token will expire if it isn't used in 60 days. Each time refresh_token is used, its expiry date is extended by 60 days.
scope
List of scopes to which users have agreed to grant access within this access_token.
expires_in
TTL (time to live) of access token in seconds. After this time, the access_token will become invalid and you have to refresh it.
When you have the tokens, you can execute API requests with access_token.
With the OAuth authentication, we introduce a new API host — https://api-proxy.pipedrive.com.
You just need to provide this access_token in every request in the Authorization header:
GET https://api-proxy.pipedrive.com/deals -H 'Authorization: Bearer 53289:1050268:4ae2dd99663e3a8e3bd04ba5d89a21850d6fa52d'Remember that access_token is bound to the scopes your app asked permissions for from the user, so requests will be denied if they will be executed against the API endpoints that are not in these scopes.
Note that api-proxy subdomain is intended only for backend requests due to security reasons. If you try to use it on frontend, browser's cross-domain security policy will not allow this.
For example, you can also use access_token to retrieve user's data from the /users/me
endpoint and then generate an account for this user using the received data. In this way, the user has an account on your app's side and doesn't need to worry about additional registrations.
The access_token has a lifetime. After a period of time which was returned to you in expires_in JSON property, the access_token will be invalid and you cannot use it to get data from API anymore. To refresh the access_token, you must use the refresh_token. You need to execute HTTP request to the OAuth server:
POST https://oauth.pipedrive.com/oauth/tokenContent-type for the request must be application/x-www-form-urlencoded.
Authorization
Base 64 encoded string containing the client_id and client_secret values. The value should be "Authorization: Basic <base64(client_id:client_secret)>".
grant_type
Since you are to refresh your access_token, you must use the value "refresh_token".
refresh_token
The refresh token that you received after you exchanged the authorization code.
If all data is correct, you will receive a response with the JSON data:
access_token
The new access token you need to use for accessing the user's data via API. access_token expires after 60 minutes.
token_type
The format of the token. Always "bearer".
refresh_token
The refresh token which is needed when you refresh the access_token. The same refresh token will be issued in the response with the expiry window extended by 60 days.
scope
List of scopes to which users have agreed to grant access within this access_token.
expires_in
TTL of access token in seconds. After this time, the access_token will become invalid and you have to refresh it.
Further reading
| Handling user app uninstallation |
| State parameter |
| FAQ |