App Login Flow for Teamwork APIs
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.
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
`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
`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.
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).
`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).
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:
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
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.:
"name": "My Awesome App",
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.
If you have any feedback or suggestions, feel free to contact us at email@example.com.