Authenticate via App Login Flow

This guide walks you through using Teamwork’s App Login Flow to authenticate users safely and obtain an access token to perform actions on their behalf.

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.

Before using this guide, you must first register your app in the Teamwork Developer Portal:

  1. Review the Teamwork.com Developer Portal guides

  2. Visit the Developer Portal at https://{yourSiteName}.teamwork.com/developer

  3. Create a new app.

  4. Once created, open your app and go to the Credentials tab.

  5. You’ll find all the necessary fields here: client_id, client_secret, and redirect_uri.

1. Step One

If your app provides functionality or services that need to work with any users Teamwork site then you should provide a generic Connect Teamwork button.

The URL to initiate the oAuth flow would be:

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

If you want to create an app that works with a specific Teamwork account that the authenticating user is a member of then the URL to initiate the oAuth flow would be:

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

URL Parameters

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

2. 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 your side.

Teamwork.com has multiple data center regions but you do not need to worry about making requests to multiple regions, as App Login Flow will handle everything.

3. 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).

4. 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"
}

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

When your app is in development mode it will only available for your Teamwork account.

Getting User Information

When you have a Bearer Token for a user you can call an API endpoint to get information about that user by making an authenticated request to

https://www.teamwork.com/launchpad/v1/userinfo.json

This will return a response that you should store and can use for your app. This is useful if your app allows for multiple Teamwork.com accounts to be authenticated for a single user

Getting a users information

GET
https://www.teamwork.com/launchpad/v1/userinfo.json
{
  "sub": "589962_274280",
  "externalCustomerId": "589962_274280",
  "email": "emailaddress@gmail.com",
  "given_name": "Johnny",
  "family_name": "Appleseed",
  "picture": "https://s3.us-east-1.amazonaws.com/TWFiles/589962/userAvatar/userImg_589962_274280.png",
  "user_id": 274280,
  "installation_id": 589962,
  "url": "https://apple.teamwork.com/"
}

Publishing your app

If you would like to publish your app and make it available for everyone, please contact integrations@teamwork.com

Our team will guide you through the approval process and ensure your app is functioning as intended.

Feedback

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