Authenticating with TeamGantt

🎉 Check out our interactive OAuth2 documentation here -- https://auth.teamgantt.com/docs/.

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. Simply join the client_id and client_secret with a colon and base64 encode the result (this is a standard for HTTP Basic auth -- you can find this built in to tools like Postman)

const authHeader = `Basic ${btoa([clientId, clientSecret].join(":"))`; 
// Basic NDQwNzFlYTEtMjg1YS00ODc3LTlkZjctN2IyZTA3MTdjZWVjOmFzamtsbmRzYWtqbGRubWtzYWpkbmpzYWtkbiBrc2FqaDg5MnUxMzRqM3drbmV3cXUzMm53ZWprZXJuMjgzajQz

POST /oauth2/token HTTP/1.1
Host: auth.teamgantt.com
Authorization: Basic yourBase64EncodedString
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 (encode each value, not the whole request). The parameters are joined on the query string, not sent in the body. If you're having issues getting past this step and have special characters in your password, you may want to double check your encoding.

  • 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. Each refresh token has a 30 day expiration. 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.jwt

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. Since you've already authenticated the client to obtain your refresh token, you do not need to send the authorization header this time.

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

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

Still need help? Contact Us Contact Us