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. If you want to create an OAuth application, please contact us at [email protected]. Send us your desired redirect URLs and we will respond with your credentials.

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.

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.

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 receive 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.

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

📘

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.

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

📘

💡 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:

Authentication: Basic MTIzYWJjOjQ1NmRlZg==

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.

Similar to Step 3, your request MUST be authenticated with Basic authentication using your OAuth application Client ID and Client Secret.

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.

Front OAuth server response will include two tokens (the new API token in the access_token param and the same, or new refresh_token in the refresh_token param) and the access_token expiration time in the expires_at param.

When a refresh_token is about to expire, it will automatically be refreshed by Front's OAuth server. Beyond saving that new request_token from the token request response, no implementation is required on your end to receive a new refresh_token.

Please securely store the refresh_token from this step, as this refresh_token will be automatically refreshed when necessary. Otherwise, the refresh_token from Step 3 will expire in six months and the OAuth flow will start from Step 1 again.

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