Visit API Community

OAuth 2.0 Authorization

Wrike API uses the OAuth 2.0 protocol for authorization. The OAuth 2.0 Authorization Framework protocol is described in http://tools.ietf.org/html/rfc6749. OAuth standard defines four flows for different use cases: authorization code, implicit, resource owner password credentials, and client credentials. At the moment, we support only authorization code flow.

This documentation contains a brief description of the OAuth 2.0 authorization process. For details, please see [RFC6749, 4.1.].

  1. Explore OAuth 2.0 authorization flow
  2. Skip OAuth 2.0 using permanent access token

Initial Setup

Before you get started with OAuth 2.0 authorization, you’ll need to register and properly set up the Wrike API application. Each application is assigned a unique Client ID and Client Secret which will be used in the OAuth flow. You can find the client credentials of your application and manage other options on App Console. Screenshot below demonstrates the configuration section of any application.

Please note the “Client ID” and “Client secret” fields as you will need them on the next steps.

However, if you created your application by filling out the form on the Get Started page you will receive your client credentials by email.

OAuth 2.0 authorization flow

1. Requesting authorization code [RFC6749, 4.1.1.]

To start the authorization process, the user should click on the link in your application that will direct him to the following URL:

https://login.wrike.com/oauth2/authorize/v4?client_id=<client_id>&response_type=code

Please note “client_id” parameter above - it should exactly match “Client ID” field you get from App Console on the previous step.

The authorize URL can also contain the optional parameters. See details about request parameters in the table below:

Parameter Required description
client_id Required The client_id you obtained in the Initial Setup.
response_type Required Whether the endpoint returns an authorization code. For web applications, a value of code should be used.
redirect_uri Optional URI where the response will be redirected. We assume that you have a working web server with a public address that can correctly handle Wrike requests.
Redirect URI should comply with OAuth2 standard requirements and utilize HTTPS protocol. Use https://localhost for local development.
state Optional An arbitrary string that will be included in the response to your application at the end of OAuth flow.
This parameter is intended to preserve some state object set by the client in the authorization request, and make it available to the client in the response. The main purpose of this is preventing Cross Site Request Forgery (CSRF).
However “state” parameter is just a string, so you can include anything that might be useful for your application.
scope Optional OAuth scopes allow you to specify exactly how your application needs to access Wrike data. This parameter is expressed as a list of comma-delimited, case-sensitive strings. You can find scopes required for each API method in the corresponding section. For example, “Create Task” API method requires the following scopes: Default, wsReadWrite

2. Handling authorization code [RFC6749, 4.1.2.]

After clicking the authorization URL from the first step, the user is redirected to the Wrike login page (if they aren't already logged in).

The user will be asked to enter the email they use to log in to Wrike and then click "Next".

They'll be asked to enter their password on the next step.

If a user is a member of multiple Wrike accounts they will need to choose which account the API application is allowed to work with.

After entering a password and selecting an account the user is redirected to a consent page for confirmation.

If the user grants access on the consent page, then they will be redirected to the redirect_uri with the code parameter set to the authorization code and state parameter (if one was included). Please note that the authorization code is only valid for 10 minutes.

3. Exchanging authorization code for access token [RFC6749, 4.1.3.]

Access credentials are requested by executing POST request to a token URL with an authorization code.

POST https://login.wrike.com/oauth2/token
  //Parameters:
  client_id=<client_id>
  client_secret=<client_secret>
  grant_type=authorization_code
  code=<authorization_code>

All parameters here are mandatory. See details about them in the table below:

Parameter Required description
client_id Required The client_id you obtained in the Initial Setup.
client_secret Required The client_secret you obtained in the Initial Setup
grant_type Required Must be authorization_code
code Required The authorization code you retrieved on the previous step

CURL example:

curl -X POST -d "client_id=&client_secret=<client_secret>&grant_type=authorization_code&code=<authorization_code>" https://login.wrike.com/oauth2/token

Response example:

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "token_type": "bearer"
  "expires_in": "3600",
  "host": "www.wrike.com"
}

Please notice the "host" parameter. Wrike stores customer data in several data centers located in USA and European Union and you need to use a specific base URL to access user's data, based on where it is located. All the following requests on behalf of this user should be done using the base URL which you build by using the "host":

https://<host>/api/v4

Please review the Overview section of the documentation to get more details on how we store customer data and why you need to use different base URLs.

4. Using access token

Every request to the API should be done using the HTTPS protocol with the access token, which should be passed in the authorization header (preferred option) or the access_token parameter. For all requests, you should be using the base URL which you built based on the "host" parameter passed to you on the previous step.

Let’s assume that we want to obtain information about yourself. Thus we have to execute the following request:

curl -X GET -H "Authorization: bearer " https://www.wrike.com/api/v4/contacts?me=true

You’ll receive the response similar to:

{
  "kind": "contacts",
  "data": [
    {
      "id": "KUAJ25LC",
      "firstName": "Test",
      "lastName": "User",
      "type": "Person",
      "profiles": [
        {
          "accountId": "IEAGIITR",
          "email": "test.user@myapp.com",
          "role": "User",
          "external": false,
          "admin": false,
          "owner": true
        }
      ],
      "avatarUrl": "https://www.wrike.com/avatars//7E/A2/Box_ffdf2a2e_84-84_v1.png",
      "timezone": "Europe/Moscow",
      "locale": "en",
      "deleted": false,
      "me": true
    }
  ]
}

Each access token is valid for one hour. After the access token has expired, the application should refresh it to continue.

The server response for an expired access token will be as follows:

{
  "error": "not_authorized",
  "errorDescription": "Access token is unknown or expired"
}

If you're using the wrong base URL, the server will respond with a 401 error:

{
  "error": "not_authorized",
  "errorDescription": "Access token is unknown or invalid"
}

5. Refreshing access token [RFC6749, 6.]

The access token is refreshed by a POST request to a token URL with a refresh token. Please bear in mind that you initially get a pair of tokens by querying the https://login.wrike.com/oauth2/token endpoint, but to refresh the token you need to use the specific base URL, which you built based on the "host" parameter passed to you in the second step.

POST https://login.wrike.com/oauth2/token
  //Parameters:
  client_id=<client_id>
  client_secret=<client_secret>
  grant_type=refresh_token
  refresh_token=<refresh_token>
  scope=<scope>

See details about parameters in the table below:

Parameter Required description
client_id Required The client_id you obtained in the Initial Setup.
client_secret Required The client_secret you obtained in the Initial Setup
grant_type Required Must be refresh_token
refresh_token Required The refresh token you retrieved in step 3
scope Optional OAuth scopes allow you to specify exactly how your application needs to access Wrike data. This parameter is expressed as a list of comma-delimited, case-sensitive strings. You can find scopes required for each API method in the corresponding section. For example, “Create Task” API method requires the following scopes: Default, wsReadWrite

curl -X POST -d "client_id=<client_id>&client_secret=<client_secret>&grant_type=refresh_token&refresh_token=<refresh_token>&scope=<scope>" https://login.wrike.com/oauth2/token

Permanent access token

Generally for production purposes, OAuth 2.0 is the prefered method of authorization in the Wrike API. However if you’d like to simply test the API features or create an application which is not intended to be used by multiple users, you can use an alternative approach — the permanent token.

The permanent token is a normal token that never expires: you can obtain it once and then use it as long as you want without needing to refresh or re-authenticate. This means you can build standalone integrations without any web server to support the OAuth 2.0 authorization flow.

Obtaining a permanent token

To receive a permanent token you need to open your application on the App Console and click “Obtain token”.

A pop-up window opens where you must:

  • Enter your password.
  • (If part of multiple accounts) select which account your app is supposed to work with.

That’s it. The ease of getting started is why the permanent token is the best way to begin working with Wrike's API. But be careful! The permanent token allows applications to gain access to all data in a certain Wrike account on your behalf. Keep your permanent token private and revoke it when you no longer need it.

Please note that your token is only shown once - write it down and keep in a safe place.

Revoking a permanent token

To revoke a previously created permanent token, you need to open your application App Console, find your token, and click “Revoke token” link.

Next Steps

Explore API methods to get maximum value from your Wrike integration. If you have any questions or feedback, feel free to contact Wrike Support Team or visit our API Community section on the Wrike Help portal.