Migrating existing integration users

If you are a partner with an existing API token integration, you may want to migrate your existing integration's users to a Marketplace app.

It's possible to exchange the API token to a pair of access and refresh tokens using a custom grant type. You must execute this HTTP request to the OAuth server:

POST https://oauth.pipedrive.com/oauth/token

In order to execute the request, your request has to be authenticated via HTTP Basic Auth with the values of client_id and client_secret.

Header parameterDescription
AuthorizationBase 64 encoded string containing the client_id and client_secret values.
Value should be "Authorization: Basic <base64(client_id:client_secret)>".


Note that authentication could also be done by providing values for client_id and client_secret in the request body, but it's not recommended. Use it only when you cannot use HTTP Basic Auth approach.

Body parameterDescription
grant_typeSince you are trying to exchange an API token to a pair of tokens, you must use value "exchange_api_token".
api_tokenAPI token of the user


Have in mind that each api_token can be exchanged only once, you have one chance for this operation. In case of problems, please contact [email protected]

If all data is correct, you will receive a response with the JSON data:

JSON key nameDescription
access_tokenAccess token you need to use for accessing user's data via API
token_typeThe format of the token. Always "bearer"
refresh_tokenRefresh token which is needed when you refresh access_token
scopeList of scopes selected in the app's settings
expires_inTTL of access token in seconds. After this time token will become invalid and you have to refresh it
api_domainThe base URL path, including the company_domain, where the requests can be sent to.

When the exchange of the tokens was successful, all users who were previously using the API token integration, will receive an email notifying them about the following:

  • the integration has now been updated to an OAuth app,
  • the OAuth app has been installed to their company,
  • the user needs to confirm the permissions the app has in their account before starting to use it.

The app will also appear in the user's Settings > Tools and apps > Marketplace apps page.


Now you should delete the API token, because from this point on your app must only use OAuth authentication.