Access Token:
   

Introduction

The Producteev API is organized around REST. Our API is designed to have resource-oriented endpoints (URLs) and make an extensive use of the HTTP technology. We use HTTP verbs to define actions, HTTP response codes to indicate the status of an API call and also HTTP Headers for Authentication.

JSON is the only format we support for both Request and Response, even when something goes wrong and we need to send you an error message.


1. Request an API Key

To get an API key, please go to the Apps tab in Producteev settings and create a new client. After providing the name, description and the OAuth redirects URL of your app, you'll receive a client id and a client secret.

 

2. Authentication: OAuth 2.0 Flows

Flow for 3rd Party Apps

Using the Authorization Code Grant Flow

For this, you will need your client id & secret. Connect to

 https://www.producteev.com/oauth/v2/auth?client_id=YOURCLIENTID&response_type=code&redirect_uri=http%3A%2F%2Fwww.yoururlencoded.com

Note that the redirect_uri must be url encoded.
The user will be redirected automatically to https://www.producteev.com/oauth/v2/auth_login for authentication.

Then will be automatically redirected to https://www.producteev.com/oauth/v2/auth?client_id=YOURCLIENTID&redirect_uri=http%3A%2F%2Fwww.yoururlencoded.com&response_type=code for Authorizing your 3rd-Party app to access his data.

If he accepts, he's redirected to http://www.yoururlencoded.com/?code=ARANDOMCODE

Your app must handle the code and then call

https://www.producteev.com/oauth/v2/token?client_id=YOURCLIENTID&client_secret=YOURCLIENTSECRET&grant_type=authorization_code&redirect_uri=http%3A%2F%2Fwww.yoururlencoded.com&code=ARANDOMCODE

The authorization code is only valid for 30sec!

And finally the app receives the token:

{"access_token":"dy0PNO8RavMQfL4yIu6nDxj64uDlg8uFlvzh866Cp5g",
"expires_in":3600,
"token_type":"bearer",
"scope":null,
"refresh_token":"xo3WhNbrpI6CusPvvoaGegEqSRUhqmETeZ05VloYWsA"}

Note: As today, the access_token are actually valid for 30 days, refresh token are valid for 90 days.

Using the Implicit Grant Flow

This flow is a little bit different, and do not need to handle the auth code. First connect to (response_type is now token)

https://www.producteev.com/oauth/v2/auth?client_id=YOURCLIENTID&response_type=token&redirect_uri=http%3A%2F%2Fwww.yoururlencoded.com

Like the previous flow, the user must authenticate then authorize the app to access his data

The user is automatically redirected to

http://www.yoururlencoded.com/#access_token=Y6ORsURnaSY2ZP9j69Hp_3nXuwdXrLJSf57l8k5A4h0&expires_in=3600&token_type=bearer&refresh_token=39V4-CVWX5cbuqiOagDyGyvbNJ5zPMs-PIV2SUUnh2s

And your app must handle the user token.

How to request a new access token using the refresh token

If you get a 400 Bad Request return, it may be because the token has expired (check the error message). In that case, you can request a new access_token using the refresh token you got when you received the access token. Refresh tokens are valid for 90 days and can be used only once.

To get a new access token call the token endpoint, with your client id, client secret, grant type=refresh token and the refresh_token.

https://www.producteev.com/oauth/v2/token?client_id=YOURCLIENTID&client_secret=YOURCLIENTSECRET&grant_type=refresh_token&refresh_token=THEREFRESHTOKEN

You will receive a new access token and a new refresh token

{"access_token":"aOPV5zbBV7tM5DrmvacmBmO82uqfRUAZ3WPGPy68fug",
"expires_in":3600,
"token_type":"bearer",
"scope":null,
"refresh_token":"BEKdhP106G1L4oYB0vN3WuU4tTf7KYa2rxFrUvnF4go"}

If you provide an expired refresh_token you will get an error message

{"error":"invalid_grant",
"error_description":"Refresh token has expired"}

In that case, you need to request a new token using one of the available flow.

Make some API Calls

Now that you have an access_token, you can make API calls on the behalf of this user. Either add it to the query string

 https://www.producteev.com/api/someendpoint?access_token=THEACCESSTOKEN

Or simply set the Authorization header of your request with Bearer THEACCESSTOKEN

 

3. Errors

Producteev use the HTTP response code to indicate success or failure of an API call.

As a generic convention, you can assume codes in the 2XX ranges indicate success, codes in the 4XX ranges indicate an error based on the information you provided or the action you wanna do, codes in the 5XX ranges indicate something is wrong with the Producteev's API servers.

Error CodeUsage
200 - SuccessThe object(s) are returned in the Response Body
201 - CreatedYour object has been created (and is embedded in the Response Body)
204 - No ContentYour request was processed but doesn't return any information/object (e.g when you delete an object)
400 - Bad RequestA required parameter is missing or invalid.
401 - UnauthorizedYou need to provide a (valid) access token.
403 - Access DeniedYou don't have the permission to access this resource.
404 - Not FoundThe resource you try to access doesn't exist.
409 - ConflictYour request was valid but we could not satisfy it due to a constraints problem.
{
  "error": "Bad Request",
  "error_description": "The content you sent isn't a valid JSON.",
  "error_code": 400
}
  • error: Generic error type
  • error_description: A human-readable message giving more details about the error.
  • error_code: HTTP Status Code (repeated as a convenience, will not be included on errors related to OAuth)
 

4. Producteev Objects

Every Objects in the API Extends from a base Producteev Object class.

They all share the same basic properties:

PropertyDescription
id:Unique Identifier of the object (String)
created_at:Date when the object was created
updated_at:Date when the object was last updated
deleted_at:If the object is deleted, the date when it was deleted will be returned
 

5. Task Permissions

Tasks are the main objects in Producteev. Each task object retrieved from the API has a dynamic attribute permissions. This attribute is an integer equals to the sum of all the permissions. In order to know if you can do an action you must translate this integer to its binary representation. Below is the enum we use in the iOS app. As you can see the first bit indicates if you can delete the task or not, the second if you can move this task to another project...

typedef enum {
    PDTTaskPermissionCanDelete              = 1 << 0,
    PDTTaskPermissionCanMove                = 1 << 1,
    PDTTaskPermissionCanEditTitle           = 1 << 2,
    PDTTaskPermissionCanEditResponsible     = 1 << 3,
    PDTTaskPermissionCanEditFollower        = 1 << 4,
    PDTTaskPermissionCanPostNote            = 1 << 5,
    PDTTaskPermissionCanEditLabel           = 1 << 6,
    PDTTaskPermissionCanEditSubtask         = 1 << 7,
    PDTTaskPermissionCanEditStatus          = 1 << 8,
    PDTTaskPermissionCanEditDeadline        = 1 << 9,
    PDTTaskPermissionCanEditPriority        = 1 << 10,
} PDTTaskPermissions;

Example: if permissions = 4095, its binary representation 11111111110. You can do everything on the task except delete it.