Authentication

​

Authentication

Fax.Plus API offers two methods for authentication:

• Personal Access Tokens (PATs) (Recommended)
• OAuth2 Authorization Code

​

Option 1: Personal Access Tokens (PATs)

To generate a new token, go to the Integrations page in your account settings. Scopes Personal Access Tokens can be generated with different scopes. Each scope grants access to a specific set of endpoints. The available scopes are: List of available scopes: fax:all:read Grants read-only access to all fax-related operations, including viewing faxes, users, members, and numbers. fax:all:edit Grants full access to all fax-related operations, allowing editing and management of faxes, users, members, webhooks, and numbers. fax:webhook:read Allows read-only access to webhook configurations, enabling retrieval of webhook details. fax:webhook:edit Grants full access to manage and modify all webhook configurations. fax:fax:read Allows viewing and listing of all faxes, including access to outbox lists, fax files, and reports. fax:fax:edit Grants full permissions to manage and edit faxes, including operations on the outbox, files, and fax details. fax:user:read Allows viewing of the current user’s details (PAT owner). fax:user:edit Grants permission to update the current user’s details (PAT owner). fax:member:read Allows viewing of account and member details, including retrieving account and member-specific information. fax:member:edit Grants permission to update member details and manage account-related member information. fax:numbers:read Allows retrieval and listing of fax numbers. fax:numbers:edit Grants full permissions to manage and edit fax numbers, including all operations related to numbers.

​

Option 2: OAuth2 Authorization Code

Fax.Plus API also employs the OAuth2 Authorization Code flow for getting and refreshing the authentication token. This flow requires:

• explicit access confirmation from the user
• redirect URL to which user will be redirected after logging in

It is not required for the redirect URL to be accessible from any place other than user’s localhost. For a standalone app it is possible to use a micro HTTP server to get the redirect, fetch the authorization code from it, and shut the server down.

​

OAuth2 Authorization Code Grant

The first step is to obtain an authorization code. Redirect the user to the URL https://accounts.fax.plus/login providing the following query parameters:

• client_id - your client ID
• redirect_uri - one of your registered redirect URIs
• response_type=code
• scope=all

Let’s assume we have http://my.web.app as the registered URI. This URI should be accessible to the user. https://accounts.fax.plus/login?response_type=code&client_id=CLIENT_ID&redirect_uri=http://my.web.app&scope=all On the redirected page, the user will be asked to log in and authorize the API. After the permission is granted, the user will be redirected to the given redirect URI with the authorization code as a code query parameter. For example, http://my.web.app?code=XXXXXX The next step is to obtain an access token. The client must send a HTTP POST request to the base URL https://accounts.fax.plus/token with the following parameters:

• Headers:
  • Content-type: application/x-www-form-urlencoded
  • Authorization: Basic XXX where XXX is the base64 encoded string CLIENT_ID:CLIENT_SECRET
• Parameters (url-encoded in query or body):
  • grant_type=authorization_code
  • client_id=YOUR_CLIENT_ID
  • code=AUTHORIZATION_CODE_FROM_PREVIOUS_STEP
  • redirect_uri=YOUR_REDIRECT_URL

Note: when using 3rd party OAuth libraries, ensure that the Authorization header is properly composed, and that the client ID is passed in the request body. Most libraries require additional flags to be set to enable this behavior. If the request was successful, you will be granted an access token in JSON format. This token should be passed as a Bearer Token inside the Authorization header with every request.

​

Refreshing An OAuth2 Access Token

To renew your access token, make an HTTP POST request to the base URL https://accounts.fax.plus/token, passing the refresh token that you have received when obtaining the initial access token as a refresh_token query parameter. Add the grant_type parameter equal to the refresh_token. https://accounts.fax.plus/token?grant_type=refresh_token&refresh_token=REFRESH_TOKEN Use the same Authorization header as the one you used for obtaining the access token. In the response, you will receive the same JSON structure as the one returned when issuing the access token. The refresh token will remain valid until the user requests a new access token, or revokes the permissions given to the client.