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.
Name | Type | Description |
---|---|---|
response_type | string | Must be set to code . |
client_id | string | Client ID of your OAuth application. |
redirect_uri | string | The URL in your application where users will be redirected after authorization. |
state | string (optional) | Used to protect against cross-site request forgery attacks. |
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.
Name | Type | Description |
---|---|---|
code | string | Temporary authorization code to exchange for an API token. |
state | string (optional) | State provided 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"
}
Body parameter | Type | Description |
---|---|---|
code | string | The temporary authorization code received in step 2. |
redirect_uri | string | The URL in your application where users will be redirected after authorization. It MUST be the same URL as the one used in the step to request an authorization code. |
grant_type | string | The grant type used to get the authorization code. Needs to be authorization_code |
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"
}
Body parameter | Type | Description |
---|---|---|
refresh_token | string | The refresh token received in step 3. |
grant_type | string | The grant type used to get the authorization code. Needs to be refresh_token |
Updated about 1 month ago