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.
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.
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.
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 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"
}
Name | 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 |
💡 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==
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"
}
Name | Type | Description |
---|---|---|
refresh_token | string | The refresh token recieved in step 3. |
grant_type | string | The grant type used to get the authorization code. Needs to be refresh_token |
Updated 7 months ago