Visit API Community

Migration from API v3

Overview

Wrike API v4 is a new generation of Wrike API built for improved security and scalability. The main difference between Wrike API v4 and v3 is that the new version can access data from only one account at a time. Method URIs were also changed accordingly.

Migration Process

Wrike API v4 is not compatible with Wrike API v3. This page will take you through the migration process.

To migrate your applications to API v4:

  • Change the version identifier from “v3” to “v4” in all request URIs.
  • Use a new authorization URI.

If your integration accesses data from one Wrike account, just get rid of per-account method URIs (see below).

If your integration accesses data from multiple Wrike accounts simultaneously, you might need to revisit the authentication flows so that data from each account is gathered with a different access token.

Access token for v4 contain information about which account it works with. Therefore, existing API v3 permanent tokens need to be migrated (reissued) to API v4. API v4 tokens will work with API v3 code, so you can migrate your tokens prior to migrating the calling code. Check the section below for details about migrating permanent tokens.

Differences between Wrike API v3 and v4

Use the table below to learn about the differences between method URIs in Wrike API v3 and v4. Note that:

  • Old URIs will no longer work.
  • New URIs always gather data from the account that the token was obtained for, so all client code needs to be updated accordingly. Authorization URI has changed to allow account selection during the login process.
Method Type API v3 URI API v4 URI Comments
GET /oauth2/authorize /oauth2/authorize/v4 New authorization flow allows user to select account to log in to
GET /accounts/{accountId}/contacts /contacts
GET, POST /accounts/{accountId}/folders /folders
GET, POST /accounts/{accountId}/groups /groups
GET, POST /accounts/{accountId}/invitations /invitations
GET, POST /accounts/{accountId}/workflows /workflows
GET, POST /accounts/{accountId}/customfields /customfields
GET /accounts/{accountId}/tasks /tasks
GET /accounts/{accountId}/comments /comments
GET /accounts/{accountId}/timelogs /timelogs
GET /accounts/{accountId}/timelog_categories /timelog_categories
GET /accounts/{accountId}/attachments /attachments
GET /accounts/{accountId}/accounts /account API v4 returns information about one account only (the one that the access token was granted for)
PUT /accounts/{accountId} /account API v4 only modifies information about one account (the one that the access token was granted for)
GET /accounts/{accountId} - There is no way to obtain information about multiple accounts in API v4

Permanent Token Migration

API v4 tokens contain information about the account they work with and can be used with code calling API v3. On the contrary, v3 tokens will not work with code calling API v4. The following table illustrates this:

API v3 code API v4 code
API v3 token
API v4 token

Therefore, the recommended migration procedure for existing applications using permanent token is to migrate token first, then migrate API calling code.

Note! Once you generate API v4 token, you will have 24 hours to replace your API v3 token before it expires.

To migrate a permanent token:

  1. Click your profile picture and select “Apps and Integrations”.
  2. Switch to the API tab.
  3. Click “Configure” to the right of the app whose token you want to migrate.
  4. Scroll to the bottom of the page and click “Migrate to v4” next to the token.
  5. Select the account which the token should work with and enter your password.
  6. Click “Obtain token”.
  7. Copy the token - it will only be shown once.
  8. Replace the token in your app and check that it works.

Refresh Token Migration

If your application stores the refresh token that is used to obtain a new access token when it expires, that token needs to be migrated to v4 as well, in order to work with the new API. The service method below can be used to migrate valid refresh tokens from v3 to v4. You’ll just need to add information about which account the token should work with.

POST https://www.wrike.com/oauth2/convert_v3_token
//Parameters:
refresh_token=<v3 refresh token>
//Either accountId or account_enc is required
accountId=<account id that v4 token will work with>
account_enc=<encoded account ID as returned by Query Account method>

Sample response below, it will contain v4 refresh and access tokens:

{
    "refresh_token": <v4 access token>,
    "access_token": <v4 access token>,
    "host": "www.wrike.com",
    "expires_in": <new access token expiration period>
}

CURL example:

curl -X POST -d "accountId=<accountId>&refresh_token=<refresh_token>" https://www.wrike.com/oauth2/convert_v3_token

Get Help

If you have any questions or need help regarding the migration, please post on our API community forum.