OAuth

This guide demonstrates the steps required to make an API requests using OAuth Client Credential.

1. Obtaining an Client Credential

To obtain a Client Credential for HeyTeam, you can simply reach out to us and request one. HeyTeam should be able to provide you with a Client Credential relatively quickly, and once you have it, you can use it to access our API services.

🚧

Keeping your Client Credential safe and secure

The Client Credential - consists of Client ID and Client secret.

We recommend you to keep these Client Credentials safe and secure.

2. Exchanging for an access token

Once you obtained the Client Credential, you will use it to exchange for an access token.

To make this exchange, you will need to make a POST request to HeyTeam 'api/oauth/token' endpoint.

Below is an example call to the 'access_token' endpoint; the values of client_id and client_secret are the Client ID and Client secret you have obtained in the previous step :

curl https://[your-domain].heyteam.com/api/oauth/token \
  -X POST \
  -H 'Content-Type: application/json' \
  -d 'client_id=985*****-****-****-****-*********2h4' \
  -d 'client_secret=gOop******************************qH7i32' \
  -d 'grant_type=client_credentials'

On success, you will receive the following response:

{
    "token_type": "Bearer",
    "expires_in": 604800,
    "access_token": "eyJ0eXAiO*******(...)***"
}

The access_token is the OAuth access token you use to make API requests to HeyTeam. Do note that the access token has a limited lifetime. The expires_in indicates the duration in second when the token will expired from the moment it was generated (7 days by default).

3. Making a request

To make an API request to HeyTeam, include the access token in the header of the request as Authorization: Bearer 'your-access-token-value' like the following example request:

curl --request GET \
     --url https://[your-domain].heyteam.com/eapi/configuration/languages \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <your-access-token>'

If the call is successful, you should receive 200 code and a JSON response like the following :

{
    "data": [
        {
            "id": 1,
            "code": "fr-FR",
            "is_enabled": true,
            "is_default": true
        },
        {
            "id": 2,
            "code": "en-US",
            "is_enabled": false,
            "is_default": false
        }
    ]
}

4. Exchanging for a new access token

In cases where your access token expired, you can simply repeat step 2 using the same Client Credential and you should be able to obtain a new access token.

5. Revoking access

A Client Credential does not have an expiration date. However in scenario where a Client Credential is not used, lost or suspected to be used maliciously by a third party, admins can revoke the Client Credential simply by reaching out to HeyTeam.