Email: api@teamwork.com
Contact us
Need more information? Get in touch with us – we love to chat
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:
Initiate authentication by directing your user to `https://www.teamwork.com/launchpad/login?redirect_uri=XXX&client_id=YYY`.
`https://www.teamwork.com/launchpad/login?redirect_uri=XXX&client_id=YYY`
`XXX`
`YYY`
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.
`http://myservice.com/auth`
`customprotocolapp://whatever`
`chrome.identity.getRedirectURL()`
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.
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.
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).
`code`
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.
application/json
The request payload should be in JSON format and contain:
code
client_id
redirect_uri
client_secret
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.
origin
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`.
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.
Authorization
If you have any feedback or suggestions, feel free to contact us at?api@teamwork.com.