1 How do I start working with the API?
2 Is there a fee or do you need a specific Wrike subscription plan to use the Wrike API?
3 What is the difference between versions of the API?
4 Does the API support users on European Data Center (EU DC)?
5 What is the general scope of API requests? I see that there's a complex Access Rights policy in Wrike.
Wrike API requests are executed on behalf of the end-user, who gives consent for the third-party app through OAuth2 protocol.
The consent screen will request permissions according to the scopes, specified for app in OAuth authorization call. Each API method documentation contains information about which scopes are required. Best practice is to only request the scopes that are necessary for the application to work. The data available through the API is the data visible and accessible to that particular user according to specific sharing settings, which are described in our Help pages.
6 What kind of data can I get through the API?
7 How does that OAuth2 thing work?
OAuth2 is an open standard which describes secure ways for the end-user to grant a third-party app access to their data (in this case, data from the user’s Wrike account). Security is of paramount importance, which makes authorization more complex topic than working with Wrike API itself. Part of our API documentation is dedicated to the OAuth 2.0 authorization process and we try to stick as closely as possible to IETF specs on the subject - RFC 6749.
Here is a brief summary of the basic authorization flow:
The user is presented with Wrike’s consent screen (login is required) showing the application name and asking for permission for the app to access the user's data. If the user is enrolled in multiple accounts, an additional screen asking to select one account to work with will be shown. When the user grants access, we redirect the user to the app’s redirect URI (you must provide one when registering your application) and you can retrieve an authorization code at this URI. The code is then exchanged for a set of tokens. The access token is used for all API calls and has a short TTL, while the refresh token is only used to get new access tokens.
There are several things to bear in mind:
- You can have multiple redirect URIs for your application, but they all must use HTTPS protocol to protect the authorization code we send while in transfer. However, you can use http://localhost for development purposes without setting up HTTPS.
- Your refresh token should only be used as needed to get new access tokens, and passing tokens as parameters is a lot less secure than doing so in the headers.
- The web host for API endpoints differ depending on the datacenter that contains user’s data. For best compatibility, always use “host” parameter obtained from /oauth2/token call to construct API endpoint URLs.
Please get in touch with firstname.lastname@example.org if you have any questions!
8 I'm developing a background/UI-less/other non-conventional app - how should I work with OAuth2?
- Put the initial URL in your browser with your API credentials:
- Log in as your “technical” user in Wrike and grant access to your application.
- You will be redirected to the URI you previously specified (we allow http://localhost for convenient local development) with the authorization code as part of the URI.
- Grab the authorization code and use it in the console cURL client to exchange it for a set of tokens. Store your refresh token securely and use it to obtain fresh access tokens as they expire. From this point, your background application can run without any user interaction by relying on these tokens.
Alternatively, you can bypass OAuth completely by using Permanent Access Tokens. Be aware that Permanent tokens grant full access to user’s account, never expire and are not intended to be used in multi-user applications.
9 Are there rate limits or quotas for requests?
Our current rate limit is estimated on per-second basis which leads to approximately 200 requests per minute. A best practice: if you encounter 429 HTTP response to your requests, use retries with exponential backoff. Also note that the [GET]/tasks method returns only 1,000 results by default for each call. To get more tasks, you can use pagination.
We also have internal DDoS protection that shuts down requests that consume too much resources. This should not happen during normal usage of the API - but if you receive 429 HTTP response without exceeding rate limit above please contact us at email@example.com.