Implement OAuth authorization flow in external apps (that access Freshworks resources)

To implement the OAuth flow in your non-Freshworks app that accesses Freshservice resources,

1. Create the OAuth credentials for your app.
2. Include the requisite code in your app logic to programmatically implement the OAuth flow.
3. Test the OAuth flow from your third-party application.
4. Publish the app to the third-party Marketplace.
5. Submit your app as an External app to the Freshworks Marketplace.

To do this,

1. Place authorization-code request: In your app logic, include a UI action such as "Authorize now," which, when clicked, sends app users to the authorization server. The authorization-server URL to which the authorization-code request should be sent: https://fws-dname.com/oauth/v2/authorize.

   fws-dname.com is your Freshworks org URL. For information on this, see What is organization URL?

   What parameters should be part of the authorization-code request?

   Request parameters	Description
   response_type Mandatory	Type of response that the authorization server should return to the client. Set it as code to denote the authorization code grant type.
   client_id Mandatory	Your app’s unique identifier obtained as part of OAuth credentials creation.
   state Mandatory	Randomly generated alphanumeric string that is used to maintain state between the request and the callback.
   scope Mandatory	Level of access (to the Freshworks resources) that your app requires. You may include all or a subset of the scopes as selected in the OAuth credentials. Ensure that you do not include scopes that are not selected in your OAuth credentials. For example, for your OAuth credentials, consider that you have selected the following scopes: freshservice.solutions.view freshservice.solutions.publish freshservice.solutions.manage Therefore, in this attribute, you can specify any or all of the defined scopes, separated by spaces. Example scope=freshservice.solutions.view freshservice.solutions.publish freshservice.solutions.manage
   redirect_uri Mandatory	Redirect URL specified when creating OAuth credentials; used for sending the callback.

   Sample request URL with parameters

   https://fws-dname.com/org/oauth/v2/authorize?response_type=code&state=<random alphanumeric string>&client_id=<your_client_id>&scope=<space separated scopes>&redirect_uri=<redirect_uri>

   Sample HTML code for Authorize button

   <a href="https://fws-dname.com/org/oauth/v2/authorize?response_type=code&state=<random alphanumeric string>&client_id=<your_client_id>&scope=<space separated scopes>&redirect_uri=<redirect_uri>">AUTHORIZE</a>

2. Receive authorization code: When Freshworks receives a successful authorization-code request call, Freshworks displays the Authorization consent form. The app user response is sent to the redirect URL sent in the authorization-code request.

   Sample response call with parameters: <redirect_url>?code=4absj7xxv2h&state=10XXXX

   In your app’s client-side code, include the logic to call a callback handler and pass the authorization code received from the Freshworks Authorization server.

3. Place access-token request: In your app’s server-side code include the callback-handler logic. The handler should handle the response from the authorization server and place the access-token request. The authorization-server URL to which the access-token request should be sent: https://fws-dname.com/oauth/v2/token

   fws-dname.com is your Freshworks org URL.

   What parameters should be part of the access-token request?

   Header parameter	Description
   Authorization Mandatory	Basic token used for authentication. The format of the token will be the base64 encoding of client_id:client_secret. Example Authorization: Basic ZnXXXXXXXXXXXXXXXXXXXXXXXXXTQ5N

   Request parameters	Description
   code Mandatory	Authorization code received from Freshworks Authorization server.
   redirect_uri Mandatory	Redirect URL specified in the authorization request.
   grant_type Mandatory	Value: authorization_code Currently, Freshworks supports only the Authorization-code-grant-type OAuth.

   Sample access-token request (in CURL) with request body parameters

   curl --location 'http://fws-dname.com/org/oauth/v2/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --header 'Authorization: Basic ZndfZXhXXXXXXXXXXXXXXXX==' \
   --data-urlencode 'code=WiCXXXXXXXXXXyp_XXXXXXXXVU_SKX4PNUN_DXXXXXXXXWs_07V9-pvXXXXXXXXXXXLkC' \
   --data-urlencode 'grant_type=authorization_code' \
   --data-urlencode 'redirect_uri=https://www.sample.com'
   

4. Receive access token: In your server-side code, include the logic to receive the response of the access-token request.

   Sample success response with the requisite access token

   {
     "access_token": "APIKEYVALUEFORAPIV2ACCESS",
     "refresh_token": "REFRESHTOKENVALUEFORAPIV2ACCESS",
     "token_type": "Bearer",
     "scope": "freshservice.solutions.view freshservice.solutions.publish freshservice.solutions.manage",
   }

5. Place REST API calls to access Freshservice resources: If the scope your app requested when placing the access-token request call is granted, you can access the Freshservice resources securely through REST API calls by specifying the retrieved access token.

   Sample CURL API request that uses the retrieved access token

   curl https://domain.freshservice.com/api/v2/tickets/20'
   -X GET
   -H "Content-Type: application/JSON"
   -H "Authorization: Bearer <retrieved_access_token>"

6. Handle token lifetime: The access token has a lifetime of 30 minutes. At a regular interval, your app should send a refresh-access-token call to the authorization server and regenerate the access token. When placing a refresh-access-token call, the app should pass the refresh token as a mandatory parameter. The refresh token has a lifetime of 365 days. After the refresh token expires, the access token is not updated and all REST API calls fail with a 401 - Unauthorized error.

   To handle this,

   • If your app has a front-end component and is installed at a single-user level, in your app code, include the logic to display a Reauthorize button on receiving the 401 error. On-click the app should trigger the authorization code request and regenerate the access and refresh tokens.
   • If your app does not have a front-end component, include a logic to trigger the authorization flow for getting a new refresh token.