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 Profile > 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 *:readscopes
   • For full management, use *:editscopes
   • Consider using fax:all:reador 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