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 parameter

Description

Authorization

Base 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 parameter

Description

grant_type

Since you are trying to exchange an API token to a pair of tokens, you must use value "exchange_api_token".

api_token

API 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 name

Description

access_token

Access token you need to use for accessing user's data via API

token_type

The format of the token. Always "bearer"

refresh_token

Refresh token which is needed when you refresh access_token

scope

List of scopes selected in the app's settings

expires_in

TTL of access token in seconds. After this time token will become invalid and you have to refresh it

api_domain

The 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 update 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 > (Integrations) > Marketplace apps page.

❗️

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



Did this page help you?