Create fine-grained access for Fax.Plus API using Personal Access Tokens

Personal Access Tokens (PATs) provide secure, fine-grained access to the Fax.Plus API. This guide will walk you through the process of creating and managing tokens with appropriate permissions for your integration needs.

Creating a Personal Access Token

Access Token Generation

1. Log in to your Fax.Plus dashboard at app.fax.plus
2. Navigate to Settings > Integrations > Personal Access Tokens
3. Click on "Generate New Token"

Token Configuration

When generating a new token, you'll need to configure:

1. Token Name: Choose a descriptive name that identifies the token's purpose
2. Expiration: Set a custom expiration date (Recommended: 90 days)

Available Scopes

Select one or more of the following scopes to define the token's access permissions:

General Access

• fax:all:read

  - Read-only access to all fax-related operations

  • View faxes, users, members, and numbers
• fax:all:edit

   - Full access to all fax-related operations

  • Manage faxes, users, members, webhooks, and numbers

Webhook Management

• fax:webhook:read- View webhook configurations

• fax:webhook:edit- Full webhook management capabilities

Fax Operations

• fax:fax:read

  - Access to view faxes

  • View outbox lists, fax files, and reports
• fax:fax:edit

  - Full fax management permissions 

  • Manage outbox, files, and fax details

User Management

• fax:use:read

  - View current user details (PAT owner)

• fax:user:edit

   - Update current user details

Shop Features

• fax:shop:read

  - Browse fax numbers and check balance credit

• fax:shop:edit

  - Purchase numbers

Member Access

• fax:member:read

  - View account and member details

• fax:member:edit

  - Manage member information

Number Management

• fax:numbers:read

   - List and view fax numbers

• fax:numbers:edit

  - Full fax number management

Security Best Practices

1. Principle of Least Privilege
   • Only grant scopes that are absolutely necessary for your integration
   • Use read-only scopes when write access isn't required
2. Token Rotation
   • Rotate tokens every 90 days
   • Set a reminder for token rotation
   • Create new tokens before old ones expire to ensure continuous service
3. Token Management
   • Keep tokens secure and never share them
   • Revoke tokens immediately if compromised
   • Store tokens securely in your application's configuration

Implementation Tips

1. Scope Selection

   • For read-only operations, use 

     *:read

     scopes

   • For full management, use 

     *:edit

     scopes

   • Consider using 

     fax:all:read

     or 

     fax:all:edit

      for broad access needs

2. Testing
   • Test your integration with minimal scopes first
   • Gradually add scopes as needed
   • Verify token expiration handling in your application

Troubleshooting

If you encounter access issues:

1. Verify the token hasn't expired
2. Confirm you've selected all required scopes
3. Check if the token has been revoked
4. Ensure you're using the token correctly in API requests

Personal Access Tokens are currently managed per user - each team member creates and revokes their own tokens under Settings > Integrations > Personal Access Tokens. There is no self-serve admin control today to revoke or disable PATs for other members of the account.