App Login Flow

This guide will explain how to use our App Login Flow. 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. To register, please see this guide.

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

• code – Retrieved using the previous step above – Required Field
• client_id – This will be generated using the Developer Portal where you register your app – Required Field
• redirect_uri – This will be generated using the Developer Portal where you register your app – Required Field
• client_secret – This will be generated using the Developer Portal where you register your app – Required Field

Example:

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

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, e.g.:


{
"access_token": "tkn.v1_Yjc3MDNkYjItNWM3Ny00YTkxLWE4MjctMDVjZWY4ZjBmYmVhLTEuMS5VUw==",
"installation": {
"id": 1,
"name": "Teamwork.com Developer",
"region": "US",
"apiEndPoint": "http://hollyswebagency.teamwork.com/",
"url": "http://hollyswebagency.teamwork.com",
"chatEnabled": false,
"company": {
"id": 1,
"name": "Teamwork.com",
"logo": ""
},
"logo": ""
},
"status": "ok",
"user": {
"id": 1,
"firstName": "Developer",
"lastName": "Girl",
"email": "holly@gmail.com",
"avatar": "",
"company": {
"id": 1,
"name": "Teamwork.com",
"logo": ""
}
}
}


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

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.

‹ Back to guides