How can I setup the initial API authentication flow?

Updated

Who can use this feature?

Available on Enterprise plan.

Accessible to Owners and Admins on Web App.

To use the Fax.Plus API, you must first grant authorization for the API to access your account. After completing the authorization process, you can log in to your account.

There are two different methods for authentication:

  1. Generate and use personal access tokens.
  2. Use the OAuth 2.0 flow.
Method 1: Generate and use Personal Access Tokens

A Personal Access Token can be used as an authentication method to access the Fax.Plus API securely. This token serves as a digital signature, allowing you to make authorized requests to our API, enabling actions such as sending faxes and retrieving data to your faxes.

Follow these steps to generate a new Personal Access Token:

  1. Login to your Fax.Plus account, and go the Profile section on your Dashboard.
  2. Find the tab for Integrations.
  3. Under Fax.Plus API, find the item for Personal Access Tokens, and click on Manage.
  4. Click on Generate Token and specify the token name, expiration date, and scopes (both edit and read as scopes on the token).
  5. Make sure to Copy your Personal Access Token now, otherwise you won't be able to see it again.
Method 2: Use OAuth 2.0 flow to authorize API to access your account

Step 1: Set up initial authentication flow

  1. Login to your Fax.Plus account, and go the Profile section on your Dashboard.
  2. Find the tab for Integrations.
  3. Under Fax.Plus API, click on Activate, and collect the following data:
    • Client ID (starts with APIK-)
    • Client secret
    • Redirect URI (one of them)

      FAX.PLUS-Authenticate.png

  4. To initiate the process of authorizing the API to access your account, simply click on the provided link on this step using a web browser. This link will redirect you to a prompt where you can grant the necessary permissions: https://accounts.fax.plus/login?response_type=code&client_id=[client ID]&redirect_uri=[redirect URI]&scope=all

    FAX.PLUS-Authenticate-1.png

  5. Once permission is granted, you will be directed to the URL you specified, accompanied by the authorization code as a URL parameter:

    FAX.PLUS-Authenticate-2.png


Step 2: Send a HTTP POST request

After you have successfully authorized access, you can proceed to perform an HTTP POST to the following URL: https://accounts.fax.plus/token?grant_type=authorization_code&client_id=[client ID]&code=[authorization code]&redirect_uri=[redirect URI].

Make sure to include the following headers in your request:

    • Content-Type:  application/x-www-form-urlencoded
    • Authorization:  Basic [base64-encoded string of "client_id:client_secret"]


FAX.PLUS-Authenticate-3.png

Once completed, you will receive a response containing an access token, which remains valid for 1 hour, as well as a refresh token with indefinite validity.

Note: If your Fax.Plus account has Advanced Security Control activated, the refresh token remains valid for 30 days in accordance with security regulations. This implies that you'll need to repeat the process every 30 days to obtain a fresh refresh token.


Step 3: Get new access token

Once your access token has expired, you can obtain a fresh one using your refresh token through an HTTP POST request to the following URL: https://accounts.fax.plus/token?grant_type=refresh_token&refresh_token=[refresh token].

This process requires the inclusion of the following headers:

    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic [base64-encoded string of "client_id:client_secret"]

 

FAX.PLUS-Authenticate-4.png

 

After obtaining the access token, all subsequent API calls will require the following headers:

    • Authorization:  Bearer [access token]
    • x-fax-clientid:  [client ID]
 
 
Was this article helpful?
0 out of 0 found this helpful
More Articles in this section