OAuth

Intro to Front OAuth

OAuth 2.0 is a protocol that lets external applications request authorization to API access in a secure way. When you set up OAuth in your app, you specify which scopes the OAuth token will have access to. Customers installing your app are then asked to authorize the requested scopes so that data is sent to you from their customer instance.

Each OAuth application is assigned a unique Client ID and Client Secret which will be used in the authorization flow. The Client Secret should never be shared. To obtain your OAuth credentials, refer to Create, manage, and publish apps.

📘

OAuth is required for public integrations available to all Front customers unless you obtain an exception from us. OAuth makes it much easier for customers to install your integration through our App Store.

Token scopes

Refer to the Authentication topic to learn about the scopes available to your OAuth token.

Using OAuth with Front

Front's OAuth implementation only supports the authorization code grant type which defines a flow to get a temporary authorization token which can then be exchanged to get an API and refresh token.

1. Request authorization

To request Front API access, you need to redirect the user to https://app.frontapp.com/oauth/authorize?response_type=code&client_id=<CLIENTID>&redirect_uri=<REDIRECTURI>.

GET https://app.frontapp.com/oauth/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectURI} HTTP/1.1
Host: app.frontapp.com

// You should replace "{clientID}" and "{redirectURI}" by the values of your OAuth application.

2. Get an authorization code

If the user accepts the authorization request, Front will redirect them back to the redirect URL specified in the first step. The request will contain a code parameter as well as the state you provided in the first step. Extract the value of code from the URL to use it in the next step.

If the states don't match, you should consider the request as insecure and the process should be aborted.

GET https://yoursite.example.com/example_path?code={authorizationCode}&state={state} HTTP/1.1
Host: yoursite.example.com

// The HTTP request will depend on the param redirect_uri specified in the authorization request.

3. Exchange authorization code

Once your application receives the temporary authorization code, you need to exchanged it for an API token by sending a POST HTTP request to https://app.frontapp.com/oauth/token with the body parameters noted in the table below.

Your request MUST be authenticated with Basic authentication using your OAuth application Client ID and Client Secret base64 encoded, as shown below:

📘

Use Basic Authentication to request a token, then Bearer Authentication after that

Basic authentication is only used when making OAuth requests to the https://app.frontapp.com/ OAuth service. Otherwise, authentication will be Bearer authentication as stated in the rest of these docs.

📘

💡 Basic Authentication

The Basic Authentication string is your client ID and secret joined with a colon (:), then Base64 encoded.
For example, if:

client_id = 123abc
client_secret = 456def

The string before Base64 encoding is:

123abc:456def

The string after Base64 encoding is:

MTIzYWJjOjQ1NmRlZg==

The final header to send in the request is:

Authorization: Basic MTIzYWJjOjQ1NmRlZg==

Front's OAuth server response will include two tokens (the API token in the access_token param and the refresh token in the refresh_token param) and the access_token expiration time in the expires_at param.

Please store the refresh_token securely, as it is required to obtain a new access_token in the next step.

POST https://app.frontapp.com/oauth/token HTTP/1.1
Host: app.frontapp.com
Authorization: Basic <your_basic_credentials>

Response 200

{
    "access_token" : "",
    "refresh_token": "",
    "expires_at"   : "",
    "token_type"   : "Bearer"
}

👍

When implementing OAuth for application channels, you can leverage token instrospection URLs

After obtaining an access token for an application channel, you can allow the external service to provide a custom channel name and address during the OAuth flow by using the token instrospection for channel identification.

4. Use Refresh Token to obtain new tokens

When the access_token from Step 3 has expired after an hour, it will need be be refreshed to continue usage. When requesting resources with an expired access_token, Front's OAuth server response will return a 401 error status code, denoting that the access_token has expired.

To obtain a new access_token, send a POST request to https://app.frontapp.com/oauth/token with the refresh_token acquired in Step 3 and grant_type set to refresh_token. Refresh tokens are valid for 6 months, so as long as you request a new access token within that period, you will not have to restart the OAuth process from Step 1. Similar to Step 3, your request MUST be authenticated with Basic authentication using your OAuth application Client ID and Client Secret.

📘

Refresh tokens expire after 6 months, but aren't refreshed until the last 24 hours of expiry

When you first receive a refresh token, it will have an expiration date set six months out. You should note this expiration date. During the six months of validity, the API will return the same refresh token to you when you obtain new tokens. In the last 24 hours of validity, however, the API will return a new refresh token, which will then start a new six month period of validity. Therefore, it is important to request new tokens in the last 24 hours of the refresh token's validity period to continue extending this timeframe without having to restart the entire OAuth process.

The Front OAuth server response will include two new tokens, the access_token and the refresh_token. Store this new set of values for further use. The access token expires in 60 minutes, and the refresh token in 6 months.

Repeat this process as necessary, making sure to use the refresh token at least once before its 6 month expiration so that you can get a new set of credentials without restarting the OAuth process from Step 1.

POST https://app.frontapp.com/oauth/token HTTP/1.1
Host: app.frontapp.com
Authorization: Basic <your_basic_credentials>

Response 200

{
    "access_token" : "",
    "refresh_token": "",
    "expires_at"   : "",
    "token_type"   : "Bearer"
}