Pipedrive API Documentation

Pipedrive's API Docs

Welcome to Pipedrive's Developer Documentation. Here you'll find comprehensive guides and documentation to help you start working with Pipedrive's API, as well as the Changelog to see any relevant changes regarding the public API.

State parameter

It's your responsibility to protect the security of your app's users, because of this we strongly recommend using a state parameter provided by OAuth 2.0 to increase the security when users install the app from the Pipedrive Marketplace.

The state parameter is not automatically available in Marketplace Manager. To enable it for your app, please write to us at [email protected].

CSFR attacks

Your app can use a state parameter for making sure the response belongs to a request initiated by the same user, therefore preventing cross-site request forgery (CSFR) attacks. A CSFR attack occurs when a malicious attacker tricks the user into performing unwanted actions that only the user is authorized to perform on a trusted web application, and all will be done without involving or alerting the user.

"A CSRF attack against the client's redirection URI allows an attacker to inject its own authorization code or access token, which can result in the client using an access token associated with the attacker's protected resources rather than the victim's (e.g., save the victim's bank account information to a protected resource controlled by the attacker)." Continue reading from the source RFC-6749.

State parameter value

Have your app generate a random string and use it as a state value, unguessable by attackers. It can be a session ID, hashed user ID, or any other value you would like to use. Make sure to store this value so you can later validate the incoming state against it.

How to implement the state parameter?

Here's the simplest example of how providing the state can make your app more secure. in this example, we use the session ID as the state parameter, but you can use whatever logic you want to create value for the state.

Step 1: Your app needs to generate the state parameter value, and append it to the OAuth authorization URL (make sure the state is different for different users/requests):

<?php
session_start();
 
// Assign to state the hashing of the session ID
$state = hash('sha256', session_id());
 
// Prepare parameters
$data = [
    'client_id' => 'b4d083d9216986345b32', // The client_id of your App
    'redirect_uri' => 'https://awesomeapp.com/oauth/callback', // The redirect_uri of your App
    'state' => $state
];
 
// Build the final url
$url = 'https://oauth.pipedrive.com/oauth/authorize?' . http_build_query($data);
 
echo $url;

Step 2: Now your app must redirect the user to the OAuth authorization URL with the state parameter you just created. This URL with the state parameter should also be added to the Installation URL field in the app’s page in Marketplace Manager under the OAuth & Access scopes section.

Step 3: Once the user has authorized your app, the user will be redirected back to your app's redirect_uri. The OAuth server will return the state parameter unchanged.

Step 4: Check if the state provided in the redirect_uri matches the state generated by your app:

<?php
session_start();
 
$state = !empty($_GET["state"]) ? $_GET["state"] : null;
$code = !empty($_GET["code"]) ? $_GET["code"] : null;
 
// Check the state received with current session id
if ($state != hash('sha256', session_id())) {
    exit('State does not match!');
}
 
echo $code;

By doing so, you have made sure that the state passed to the OAuth server matches the state in the redirect_uri to where the user was redirected, thus ensuring the validity of the redirect.

In the case of the state not matching, you could assume a possible redirect by a malicious attacker.

Updated 2 months ago


State parameter


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.