OAuth 2.0 Authorization | Develop your own integration on the Wrike API

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.].

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. This parameter is required if you have more than one callback URL specified in the API application.
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
redirect_uri	Optional	Required, if the "redirect_uri" parameter was included in the authorization request as described in Section 1. Requesting authorization code, and their values must be identical.

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": "[email protected]",
          "role": "User",
          "external": false,
          "admin": false,
          "owner": true
        }
      ],
      "avatarUrl": "https://www.wrike.com/avatars//7E/A2/Box_ffdf2a2e_84-84_v1.png",
      "timezone": "US/Pacific",
      "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.]

Once the access token expires, you will need to use the refresh token to renew it. You can do this by sending 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

The refresh operation returns a new access token and a new refresh token, making the old refresh token invalid.

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.

Wrike stores customer data in several data centers. There are data centers located in the USA and European Union, you need to use a specific base URL to access user's data, based on where it is located. All the requests should be done using the base URL, which you can determine by looking at the URL in the address bar when you access your Wrike instance in a browser.

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.

Actions that revoke API tokens

API tokens (both permanent and OAuth 2.0) become revoked when:

User manually revokes the token in API app settings
User resets their password
User becomes deactivated
Admin signs in as the token author with "Log in as this user" button in AM (this action includes deactivation)
Account admin changes password strength policy
- This action logs the user out and forces the password reset, if it does not meet the requirements. However, if the password does meet the requirements, the user is not logged out, but the existing tokens still become invalidated.

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.