Authenticating with TeamGantt

We're pleased to now support standardized OAuth2 workflows for authenticating your app with TeamGantt. This article will get you set up and authenticated in no time.

Please note-- TeamGantt will continue to allow creating sessions with the previously documented /v1/authenticate API route until July 1, 2021. After this point all new login requests will need to follow the steps in this article. Any login sessions made using the former route will be accepted until September 1, 2021.

Overview

  1. Create an integration app (i.e. "client") with TeamGantt.
  2. Obtain your initial auth tokens via email and password.
  3. Authorize your requests to TeamGantt. 
  4. Exchange your refresh token with our authorization server to get a new token as needed.
  5. Optionally revoke all refresh tokens

1. Create Integration App

Head on over to your account at TeamGantt and click on Configure API Access (beta). All of your existing apps have been converted to work with our new auth flows. If you haven't created an app before, simply create a new one (the name must be unique for your account, and is only for your own reference). Once you have created an app, you will need the generated client_id and client_secret to build your request header. 

2. Obtain Initial Auth Tokens

First, you will need to exchange your email and password with our auth server in order to receive authorization tokens. In OAuth2 terms, this is called the password "grant type", in that you are obtaining access tokens based on your username/password credentials. An alternative to this will be using the refresh token grant type to get a new token.

For all grants, the endpoint will be https://auth.teamgantt.com/oauth2/token. When obtaining your initial auth tokens, you will need to provide a basic authorization header generated from your client. This is not required when using the refresh_token grant.

const authHeader = `Basic ${btoa([clientId, clientSecret].join(":"))`; 
// Basic NDQwNzFlYTEtMjg1YS00ODc3LTlkZjctN2IyZTA3MTdjZWVjOmFzamtsbmRzYWtqbGRubWtzYWpkbmpzYWtkbiBrc2FqaDg5MnUxMzRqM3drbmV3cXUzMm53ZWprZXJuMjgzajQz
POST /oauth2/token HTTP/1.1
Host: auth.teamgantt.com
Authorization: Basic yourBase64EncodedClientId:Secret
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=john@doe.com&password=topsecret

These are the required parameters for a password grant. They must be x-www-form-urlencoded.

  • grant_type=password
  • username= // your TeamGantt account email address
  • password= // your TeamGantt account password

The response, is successful, will be a JSON object containing your auth tokens. Here's an overview of them.

  • id_token
    This is the token you will use when making an authenticated request to any TeamGantt API routes. It is only valid for 1 hour after being issued. It is a standard JSON Web Token (JWT), and you can inspect the payload of this token for the "exp" claim to see when it will expire.
  • refresh_token
    This token should be securely stored by you and used to refresh your session and obtain a new id_token. It does not expire, however, you can choose to revoke all of your refresh tokens.
  • access_token
    This is special auth token used only to revoke all of your refresh tokens.

3. Authorize Your Requests

Now that you have an id_token, you will simply include this as the Bearer for your Authorization headers to TeamGantt.

GET /tasks HTTP/1.1
Host: api.teamgantt.com
Authorization: Bearer your.id.token

This will work as long as your id_token is valid. However, after an hour you will need to obtain a new id_token in order to continue using the API. This is where your refresh token comes in.

4. Exchange Refresh Token

Refreshing your id_token is even simpler than using the password grant. The endpoint, method, and content type is the same, you just need to provide different parameters.

  • grant_type=refresh_token
  • refresh_token= // your previously obtained refresh_token from the password grant
POST /oauth2/token HTTP/1.1
Host: auth.teamgantt.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=your.refresh.token

The response, if successful, will only contain an id_token and access_token, which can be used to make further requests to the TeamGantt API. If at anytime you need a new refresh_token, this can only be obtained through the password grant above. 

5. Revoke Refresh Tokens

If at any point you wish to revoke all refresh tokens that have been obtained using the password grant, you can do so with this request. Similar to the password grant, you will need to provide the basic authorization header with your client id and secret. Additionally, the request body will need to include a valid access_token from either a password or refresh grant response. This will revoke each and every refresh token that has been created for your user. There is not currently a way to revoke an individual token, though that should be supported in the future.

POST /revoke HTTP/1.1
Host: auth.teamgantt.com
Authorization: Basic yourBase64EncodedClientId:Secret
Content-Type: application/x-www-form-urlencoded

token=your.access.token