Authenticate via App Login Flow

This guide will explain how to use our App Login Flow.

Note before proceeding: If you are using the Teamwork.com API for personal use, or to do some testing, Basic Auth will be OK to use.

To use this guide, please first register your app on our Developer Portal. Creating your app will generate the necessary fields you need to continue this process.

Inside the Developer Portal, select your app, navigate to the 'Credentials' tab. Here will hold all the required fields to use our App Login Flow:

Step One

Initiate authentication by directing your user to:

https://www.{yourSiteName}.teamwork.com/launchpad/login?redirect_uri=XXX&client_id=YYY.

  • XXX is the return URI for your app/service

  • YYY is the client ID from the Developer Portal

For the redirect URI’s, you can pass URIs such as http://myservice.com/auth, customprotocolapp://whatever, or the result from chrome.identity.getRedirectURL() for Chrome extensions.

You can also pass a state query parameter which will be returned back to you in the final step.

It is up to you how you open the authentication window - you can use a modal/new window, a built-in API that handles it for you, or just open the link up in the browser.

Step Two

The user will authenticate, either by email/password or one of the other login methods, this step does not require any work from the developer's side.

You do not need to worry about making requests to multiple regions, as App Login Flow will handle everything.

Step Three

The user is returned back to the login success page, at which point we open/redirect/navigate to the provided redirect_uri (for http(s) URLs, user will be automatically redirected, otherwise a message will tell the user that it is safe to close the window, or you can close the modal/popup from your app once you have received the code).

A code query parameter is appended to the URI containing the temporary authentication token (which expires in 15 minutes), as well as the state parameter (if passed in Step 1).

Step Four

Now that you've received the code, you can close any authentication popup/modal/child window (if needed), and you must make a HTTP POST request to: https://www.teamwork.com/launchpad/v1/token.json.

A content-type header of application/json needs to be sent.

The request payload should be in JSON format and contain the following parameters.

Request Parameters

  • Name
    code
    required
    Description

    Retrieved using the previous step above.

  • Name
    client_id
    required
    Description

    This will be generated using the Developer Portal where you register your app.

  • Name
    redirect_uri
    required
    Description

    This will be generated using the Developer Portal where you register your app.

  • Name
    client_secret
    required
    Description

    This will be generated using the Developer Portal where you register your app.

Error Codes on step 4

400 Bad Requests

There are a few reasons for a 400 bad request error with the following message - The token data sent is invalid

  • Request body data being added as URL parameters.

  • Or one or more of the key values are incorrect, please check your code, client_secret, redirect_uri and or client_id values are correct and try again.

400 Bad Request - The token data sent is invalid

{
    "message": "The token data sent is invalid",
    "status": "Invalid Request"
}

400 Bad Request - Incorrect Key names

{
    "message": "Token is empty",
    "status": "Invalid Request"
}

401 Unauthorized

More than likely the code was not used within the required 15 minute window. If the request is being made within the 15 minute window the following errors will appear if incorrect with the same error code.

If outside the 15 minute window, one or more of the key values are incorrect, please check your code was created within 15 minutes of your request, client_secret, redirect_uri and or client_id values are correct and try again.

401 Unauthorized - The token provided is invalid or has expired

{
    "message": "The token provided is invalid or has expired",
    "status": "Invalid Token"
}

401 Unauthorized - Invalid required field data

{
    "errors": [
        "provided redirect_uri does not match the one in token"
    ]
}

401 Unauthorized - Invalid required field data

{
    "errors": [
        "client_id is invalid"
    ]
}

401 Unauthorized - Invalid required field data

{
    "errors": [
        "client_secret is invalid"
    ]
}

405 Method Not Allowed

Most likely when the user added a GET or PUT request instead of POST

405 Method Not Allowed

{
    "errors": [
        "Method Not Allowed"
    ]
}

Example Request - Step Four

POST
{
  "client_id": "714e6facf170413489dfab7a07c943f8ecf4622a",
  "client_secret": "aff41e68f216fc5cc184b2b2d52da7fb5706a788",
  "code": "7cc8debd-a469-4b8b-9eef-f825d4480274",
  "redirect_uri": "http://myawesomeapp.com"
}

If your app has allowed origins, an additional origin header needs to be provided.

Upon successful request (you can check), the resulting payload will contain a permanent access token under the key access_token as well as basic installation info.

You should store the access_token for all future requests, the basic installation data will provide you with the required URL under apiEndPoint.

Example Response - Step Four

{
  "access_token": "c4e0dbf21a303a7e92cf1c484dc66466e81db236362606c125ec0bdc4fd88eee9a837e14da53e3f4dbb28ffe0928714a",
  "installation": {
    "apiEndPoint": "https://myawesomeapp.teamwork.com/",
    "company": {
      "id": 1,
      "logo": "",
      "name": "Teamwork.com"
    },
    "id": 1,
    "logo": "",
    "name": "My Awesome App",
    "region": "US",
    "url": "http://myawesomeapp.teamwork.com/"
  },
  "status": "ok"
}

Step Five

You can now use the access token for authentication with our apps. The token should be passed under the Authorization header as Bearer XXX where XXX is the token.

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.