API Authentication, Rate Limits, and Best Practices

Integrate BreezeDoc with your applications using the REST API. This guide covers authentication methods, personal access tokens, OAuth 2.0, rate limits, error handling, and best practices for building reliable integrations.

Prerequisites

  • Account: Active BreezeDoc account
  • Plan: Pro or Agency plan (API access requires paid plan)
  • Access: Admin/Owner role for token generation
  • Development Environment: API client (Postman, cURL, or programming language HTTP library)
  • Documentation: API docs available at breezedoc.com/developer/docs

What is the BreezeDoc API?

The BreezeDoc REST API allows you to programmatically manage documents, templates, and recipients. Key capabilities:

  • Document Management – Create, retrieve, and send documents via API
  • Template Integration – Generate documents from templates programmatically
  • Recipient Tracking – Monitor signing status and completion
  • Team Operations – Manage team documents and templates (Agency plan)
  • Automation – Build workflows that automatically create and send contracts
  • OAuth 2.0 Support – Allow users to authenticate your third-party app

Authentication Methods

Personal Access Tokens (Recommended for Internal Integrations)

Personal access tokens are the simplest way to authenticate API requests. Use this method when building internal integrations or scripts where you control both the application and the BreezeDoc account.

When to Use Personal Access Tokens:

  • Internal automation scripts
  • Server-to-server integrations
  • Single-account integrations (no multi-user auth needed)
  • Quick prototyping and testing

Security Note: Personal access tokens grant full API access to your account. Store tokens securely as environment variables or secrets management systems. Never commit tokens to version control or expose them in client-side code.

OAuth 2.0 Clients (Required for Third-Party Apps)

OAuth 2.0 allows users to authorize your application to access their BreezeDoc account without sharing credentials. Use this method when building third-party integrations that serve multiple BreezeDoc users.

When to Use OAuth 2.0:

  • SaaS integrations serving multiple customers
  • Public applications requiring user authorization
  • Marketplace apps and plugins
  • Any app where users bring their own BreezeDoc accounts

OAuth Flow: authorization_code grant type following standard OAuth 2.0 protocol.

Creating Personal Access Tokens

Step-by-Step: Generate an Access Token

  1. Log in to your BreezeDoc account (Pro or Agency plan required).
  2. Go to Settings ➜ Integrations.
  3. Click the API tab or navigate to breezedoc.com/integrations/api.
  4. In the Personal Access Tokens section, click Create New Token.
  5. Enter a descriptive Token Name (e.g., "Production Server", "Testing Script").
  6. Click Create.
  7. Copy the token immediately – it will only be displayed once.
  8. Store the token securely in your application's configuration or environment variables.

Important: If you lose the token, you cannot retrieve it. You must delete the old token and create a new one.

Using Access Tokens in API Requests

Include your access token in the Authorization  header of every API request using the Bearer authentication scheme:

Authorization: Bearer {YOUR_ACCESS_TOKEN}

Example cURL Request:

curl -X GET https://breezedoc.com/api/documents \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Content-Type: application/json"

Example in JavaScript (Node.js):

const axios = require('axios');

const response = await axios.get('https://breezedoc.com/api/documents', {
  headers: {
    'Authorization': 'Bearer your_access_token_here',
    'Content-Type': 'application/json'
  }
});

Managing Access Tokens

  • View Active Tokens: See all tokens in the Personal Access Tokens section at breezedoc.com/integrations/api
  • Token Names: Use descriptive names to identify where each token is used
  • Revoke Tokens: Delete tokens immediately if compromised or no longer needed
  • Rotate Tokens: Create new tokens periodically for security best practices
  • Multiple Tokens: Create separate tokens for different environments (dev, staging, production)

Setting Up OAuth 2.0 Clients

Step-by-Step: Create OAuth Client

  1. Go to Settings ➜ Integrations ➜ API.
  2. In the OAuth Apps section, click Create New Client.
  3. Fill in the OAuth client details:
    • Name: Your application name (shown to users during authorization)
    • Redirect URL: Your app's callback URL where users return after authorization
  4. Click Create.
  5. Copy the Client ID and Client Secret – store these securely.

OAuth 2.0 Endpoints

  • Authorization URL: https://breezedoc.com/oauth/authorize
  • Token URL: https://breezedoc.com/oauth/token
  • Grant Type: authorization_code

OAuth Authorization Flow

  1. Authorization Request: Redirect users to the authorization URL with your client_id and redirect_uri
  2. User Consent: User authorizes your app on BreezeDoc
  3. Authorization Code: BreezeDoc redirects back to your redirect_uri with an authorization code
  4. Token Exchange: Exchange the authorization code for an access token by calling the token endpoint
  5. API Access: Use the access token to make authenticated API requests on behalf of the user

For detailed OAuth 2.0 implementation guidance, see: OAuth 2.0 Authorization Code Flow

Understanding Rate Limits

Rate Limit Policy

BreezeDoc enforces rate limiting to ensure fair usage and system stability:

  • Limit: 60 requests per minute
  • Scope: Per authenticated user (or per IP address for unauthenticated requests)
  • Reset: Limit resets every minute (rolling window)
  • Response: HTTP 429 error when limit exceeded

Rate Limit Headers

API responses include headers showing your current rate limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1672531200
  • X-RateLimit-Limit: Maximum requests allowed per minute (60)
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the limit resets

Handling 429 Errors

When you exceed the rate limit, you'll receive a 429 Too Many Requests error. Implement retry logic with exponential backoff:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{"message": "Too Many Requests"}

Best Practice: Wait for the time specified in the Retry-After  header before retrying the request.

Available API Endpoints

Documents

  • GET /api/documents – List all documents with filtering and pagination
  • POST /api/documents – Create a new document
  • GET /api/documents/{id} – Retrieve document details
  • GET /api/documents/{id}/recipients – List document recipients
  • POST /api/documents/{id}/send – Send document to recipients for signing

Templates

  • GET /api/templates – List all templates
  • GET /api/templates/{id} – Retrieve template details
  • POST /api/templates/{id}/create-document – Create a document from template

Recipients

  • GET /api/recipients – List recipients with filtering

Teams (Agency Plan)

  • GET /api/teams/{id}/documents – List team documents
  • GET /api/teams/{id}/templates – List team templates

User

  • GET /api/me – Retrieve authenticated user information

For complete endpoint documentation, parameters, and response schemas, see: BreezeDoc API Documentation

API Best Practices

Security Best Practices

  • Store Tokens Securely: Never hardcode tokens in source code; use environment variables or secrets management
  • Use HTTPS Only: All API requests must use HTTPS (HTTP is not supported)
  • Rotate Tokens Regularly: Replace tokens periodically to minimize risk of compromise
  • Revoke Unused Tokens: Delete tokens that are no longer needed
  • Limit Token Scope: Create separate tokens for different services/environments
  • Monitor Token Usage: Track which tokens are actively used and investigate anomalies

Performance Best Practices

  • Respect Rate Limits: Implement rate limit handling with exponential backoff
  • Use Pagination: Request data in pages rather than all at once (endpoints return 10 items per page by default)
  • Cache Responses: Store frequently accessed data locally to reduce API calls
  • Batch Operations: Group related operations when possible instead of making many individual requests
  • Monitor Rate Limit Headers: Check X-RateLimit-Remaining to avoid hitting limits
  • Filter Results: Use query parameters to request only the data you need

Error Handling Best Practices

  • Check HTTP Status Codes: Handle different error types appropriately (401, 403, 404, 429, 500)
  • Parse Error Messages: API returns JSON error details – log these for debugging
  • Implement Retries: Retry failed requests with exponential backoff for transient errors (429, 500, 503)
  • Validate Inputs: Check data before sending to avoid 400 Bad Request errors
  • Log API Errors: Maintain logs of API failures for troubleshooting
  • Graceful Degradation: Handle API unavailability in your application without crashing

Integration Patterns

  • Webhooks Alternative: BreezeDoc does not currently offer webhooks – use polling with pagination to check for updates
  • Idempotency: Track created documents by ID to avoid duplicate document creation
  • Status Polling: Check document completion status by fetching recipients and checking completed_at timestamps
  • Template-Based Workflow: Create templates in BreezeDoc UI, then generate documents via API

Common Integration Scenarios

CRM Integration: Auto-Send Contracts

  1. Create a template in BreezeDoc for your standard contract
  2. When a deal is won in your CRM, trigger an API call
  3. POST /api/templates/{id}/create-document with customer details as recipients
  4. POST /api/documents/{id}/send to email the contract to the customer
  5. Poll GET /api/documents/{id}/recipients to track signing status

Customer Onboarding Automation

  1. When a new customer signs up, create multiple documents from templates (NDA, Service Agreement, etc.)
  2. Use POST /api/templates/{id}/create-document for each required document
  3. Send all documents in sequence using POST /api/documents/{id}/send
  4. Track completion via GET /api/recipients with filtering

Reporting Dashboard

  1. Fetch all documents with GET /api/documents?order_by=completed_at&direction=desc
  2. Filter by completion status: GET /api/documents?completed=true
  3. Display signing metrics in your internal dashboard
  4. Refresh data periodically (respecting rate limits)

Troubleshooting

Issue: 401 Unauthorized error

Fix: Verify your access token is correct and included in the Authorization header with "Bearer " prefix. Ensure your account has an active Pro or Agency plan (API access is not available on Free plan). Check that the token has not been revoked at breezedoc.com/integrations/api. If the token was deleted or regenerated, create a new token and update your application configuration.

Issue: 403 Forbidden error

Fix: You are authenticated but lack permission for the requested resource. Verify you have access to the document or template you're trying to retrieve. For team resources, confirm your role allows the operation (Owner/Sender/Editor roles required for modifications). Check that you're not trying to access another user's private documents.

Issue: 426 Upgrade Required error

Fix: You've reached your plan's monthly document limit. Check your usage at breezedoc.com/account/plan. Wait for your monthly limit to reset (limits reset on your billing cycle date) or upgrade to a higher plan (Agency plan has unlimited documents). Free plan users: upgrade to Pro or Agency to access the API.

Issue: 429 Too Many Requests error

Fix: You've exceeded the rate limit of 60 requests per minute. Wait 60 seconds before retrying. Implement exponential backoff in your retry logic. Check the Retry-After header for exact wait time. Monitor X-RateLimit-Remaining header to avoid hitting the limit. Consider caching frequently accessed data to reduce API calls.

Issue: Token not working immediately after creation

Fix: Tokens are active immediately – if requests fail, verify you copied the complete token string. Ensure there are no extra spaces or line breaks in the token. Test the token with a simple GET /api/me request to confirm authentication works. Check that the Authorization header format is exactly: "Authorization: Bearer YOUR_TOKEN" with one space after "Bearer".

Issue: Cannot find API documentation

Fix: API documentation is available at breezedoc.com/developer/docs. You must be logged in with a Pro or Agency account to access the docs. The documentation includes OpenAPI specification with interactive examples. If the docs page returns 404, verify your plan includes API access.

FAQ

Q: Is the API available on the Free plan?

A: No, API access requires a Pro or Agency plan. Upgrade at breezedoc.com/account/plan to access the API.

Q: How many API requests can I make per day?

A: There's no daily limit – only a rate limit of 60 requests per minute. You can make unlimited requests as long as you stay within the per-minute limit.

Q: Does BreezeDoc support webhooks for real-time notifications?

A: BreezeDoc does not currently offer outgoing webhooks. Use polling to check document status by periodically calling GET /api/documents or GET /api/recipients.

Q: Can I use the API to upload PDF files?

A: The current API does not support direct PDF uploads. Create templates in the BreezeDoc UI, then use POST /api/templates/{id}/create-document to generate documents from those templates.

Q: What happens to API tokens if I downgrade my plan?

A: If you downgrade from Pro/Agency to Free, API access is revoked and existing tokens stop working. Tokens are automatically reactivated if you upgrade back to a paid plan.

Q: Can I regenerate an access token if it's compromised?

A: No – tokens cannot be regenerated. Delete the compromised token immediately at breezedoc.com/integrations/api and create a new token. Update your application with the new token.


Need more help? Contact our support team – we are here to help!

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles