Skip to main content

​
API Authentication

The PayRequest API uses OAuth2 with Personal Access Tokens for authentication. All API requests must include a valid access token in the Authorization header.

​
Creating an Access Token

1

Navigate to API Settings

Go to Settings → API Tokens in your PayRequest dashboard.
2

Create New Token

Click the Create New Token button.
3

Configure Token

  • Enter a descriptive name (e.g., “MCP Billing Agent”)
  • Select the scopes (permissions) your token needs
  • Click Create
4

Copy Your Token

Your token is only shown once. Copy it immediately and store it securely. If you lose it, you’ll need to create a new token.

​
Using Your Token

Include the token in the Authorization header of every API request: 
curl -X GET "https://payrequest.app/api/v1/invoices" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

​
OAuth Scopes

Scopes define what actions your token can perform. Request only the scopes you need for better security.

​
Available Scopes

ScopeDescriptionUse Case
billing.readRead invoices, subscriptions, transactionsDashboards, reporting, monitoring
billing.writeCreate and modify invoices and subscriptionsInvoice automation, billing workflows
billing.agentFull AI billing agent accessMCP integrations, AI assistants
customers.readRead customer informationCRM integrations, customer lookup
customers.writeCreate and modify customersCustomer sync, onboarding automation
products.readRead product catalogCatalog sync, price checks
products.writeCreate and modify productsProduct management automation

​
Default Scope

If you don’t specify scopes when creating a token, it will receive the default billing.read scope.

​
Scope Inheritance

The billing.agent scope includes all capabilities of billing.read and billing.write, making it ideal for AI-powered billing assistants.

​
Token Expiration

Token TypeExpiration
Personal Access Token6 months
Access Token15 days
Refresh Token30 days
Tokens expire automatically for security. Plan to refresh or regenerate tokens before they expire.

​
Security Best Practices

  • Never commit tokens to version control
  • Use environment variables or secret management services
  • Encrypt tokens at rest
  • Only request the scopes your application needs
  • Review and audit token permissions regularly
  • Create separate tokens for different integrations
  • Regenerate tokens periodically (every 3-6 months)
  • Revoke tokens that are no longer needed
  • Monitor for unauthorized usage
  • Always use HTTPS (enforced by our API)
  • Don’t log or display full tokens
  • Use secure headers in requests

​
Revoking Tokens

To revoke a token:
  1. Go to Settings → API Tokens
  2. Find the token you want to revoke
  3. Click the Delete button
  4. Confirm the deletion
Revoking a token is immediate and cannot be undone. Any applications using that token will lose access.

​
Error Responses

​
Invalid or Missing Token

{
  "message": "Unauthenticated."
}
HTTP Status: 401 Unauthorized Solution: Ensure you’re including a valid token in the Authorization header.

​
Insufficient Scope

{
  "success": false,
  "error": "Invalid scope(s) provided."
}
HTTP Status: 403 Forbidden Solution: Create a new token with the required scopes or update your existing token’s permissions.

​
Expired Token

{
  "message": "Unauthenticated."
}
HTTP Status: 401 Unauthorized Solution: Generate a new access token from the dashboard.

​
Example: Complete Authentication Flow

// Node.js example using fetch
const API_TOKEN = process.env.PAYREQUEST_API_TOKEN;

async function getInvoices() {
  const response = await fetch('https://payrequest.app/api/v1/invoices', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    if (response.status === 401) {
      throw new Error('Invalid or expired API token');
    }
    if (response.status === 403) {
      throw new Error('Insufficient permissions');
    }
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

# Python example using requests
import os
import requests

API_TOKEN = os.environ.get('PAYREQUEST_API_TOKEN')

def get_invoices():
    response = requests.get(
        'https://payrequest.app/api/v1/invoices',
        headers={
            'Authorization': f'Bearer {API_TOKEN}',
            'Accept': 'application/json',
            'Content-Type': 'application/json'
        }
    )

    if response.status_code == 401:
        raise Exception('Invalid or expired API token')
    if response.status_code == 403:
        raise Exception('Insufficient permissions')

    response.raise_for_status()
    return response.json()