> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.fax.plus/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://app.fax.plus/profile/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.
You have to include an **Authorization** header with a value of **Bearer TOKEN** in every request.
## 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](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](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](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](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](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.