OAuth

Intro to Front OAuth

OAuth 2.0 is a protocol that lets external applications request authorization to API access in a secure way.

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.

📘

OAuth has access to the Shared Resources permissions scope

OAuth tokens have access to Front "shared resources", which means team resources across all teams in your company. This encompasses the majority of the resources you need to build integrations. However, OAuth tokens do not have access to private resources of an individual team member (individual inboxes, tags, signatures, etc.) nor do they have access to knowledge base resources at this time. If you need access to these resources, use an API token configured with the appropriate permissions scope. A future update to Front's OAuth implementation will allow you to specify the permissions scopes that you need, but for now they default only to shared team resources.

Because the OAuth connection will allow an app to access all shared resources, the ability to connect a team's Front workspace to an app via OAuth is limited to teammates with a company admin role. If non-admins attempt to authorize the OAuth connection, they should expect the request to be rejected with a "You need to be an administrator of your Front instance to authorize this request." error response.

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"
}