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:
Click your profile picture and select “Apps and Integrations”.
Switch to the API tab.
Click “Configure” to the right of the app whose token you want to migrate.
Scroll to the bottom of the page and click “Migrate to v4” next to the token.
Select the account which the token should work with and enter your password.
Click “Obtain token”.
Copy the token - it will only be shown once.
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.