How to Create and Manage API Personal Access Tokens

Create a BreezeDoc personal access token in Settings → Integrations → Manage API Keys to call the API from your own scripts. Each token is valid for one year.

Prerequisites

  • Plan: Individual Plan or Agency Plan (both one-time purchases), including the Agency Plan free trial. The Free Plan does not include API access.
  • Account: An active BreezeDoc account, logged in.
  • Browser: A modern web browser (Chrome, Firefox, Safari, Edge).

What are Personal Access Tokens?

Personal access tokens let you authenticate with the BreezeDoc API without setting up OAuth. They provide:

  • Simple authentication - no OAuth flow; send the token in a header.
  • Full account access - a token acts as your user account, with the same access you have.
  • One-year lifetime - a token stops working one year after you create it.
  • Revocable - delete a token at any time to revoke it.
  • Multiple tokens - create a separate token for each integration.

When to Use Personal Access Tokens

Personal access tokens are ideal for:

  • Personal scripts - automating your own workflows
  • Internal tools - tools for your team or company
  • Testing - trying API endpoints during development
  • Server-to-server - backend integrations where you control both sides
  • Single-user access - applications that only access your own account

When NOT to Use Personal Access Tokens

Use OAuth 2.0 instead for:

  • Public applications - apps used by other BreezeDoc users
  • Third-party integrations - applications you distribute to others
  • Client-side apps - browser-based or mobile applications

Creating a Personal Access Token

Step-by-Step Instructions

  1. Log in to your BreezeDoc account.
  2. Open Settings and click Integrations in the side menu.
  3. In the API section, click Manage API Keys. The API Settings page opens.
  4. Scroll to the Personal Access Tokens section and click Create New Token.

BreezeDoc API Settings page showing Personal Access Tokens section with Create New Token button

  1. In the Create Token window, enter a descriptive Name for the token (for example, "Production API Script" or "Data Export Tool").
  2. Click Create.

Create Token modal dialog with Name input field and Create button

  1. The new token appears with the message: "Here is your new personal access token. This is the only time it will be shown so don't lose it!"
  2. Copy the token right away and store it securely (a password manager is a good choice).
  3. Click Close when you have saved it.

Personal Access Token revealed showing one-time display warning - copy this token immediately

Note: A token is valid for one year from the day you create it. The token list shows only each token's name, so write down the creation date and replace the token before it expires.

Token Naming Best Practices

  • Good examples: "Production Integration", "Development Testing", "Backup Script Server"
  • Poor examples: "Token 1", "Test", "My Token"
  • Include the environment: production, staging, or development
  • Include the purpose: the system or script that uses the token

Using Personal Access Tokens

Authentication Header Format

Send your token in the Authorization header of every API request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Example API Request

Using curl:

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

Using JavaScript (Node.js):

const axios = require('axios');

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

console.log(response.data);

Using Python:

import requests

headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get('https://breezedoc.com/api/me', headers=headers)
print(response.json())

For every endpoint, see BreezeDoc API: Getting Started, Endpoints and Limits.

Managing Your Tokens

Viewing Active Tokens

  1. Go to Settings → Integrations → Manage API Keys.
  2. Scroll to the Personal Access Tokens section to see every active token by name.
  3. Token values are never shown again after creation.

API Settings showing active Personal Access Token in list with Delete button for token management

Revoking (Deleting) Tokens

  1. Go to Settings → Integrations → Manage API Keys.
  2. Find the token in the Personal Access Tokens list.
  3. Click Delete next to it. The token is revoked immediately - there is no confirmation step.
  4. API requests that still use the token get a 401 Unauthorized response.

When to Revoke Tokens

  • Token exposed: committed to a public repository, shared, or otherwise leaked
  • Project ended: the integration that used it is retired
  • Security rotation: as part of regular security hygiene
  • Team member departure: someone with access to the token leaves
  • Suspicious activity: you suspect unauthorized access

Security Best Practices

Secure Token Storage

  • Never commit tokens to version control (Git, SVN, etc.)
  • Use environment variables instead of hardcoding tokens in source code
  • Store tokens in a password manager for safekeeping
  • Use a secrets manager in production (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Encrypt at rest if you store tokens in a database or configuration file

Safe Token Usage

  • Server-side only: never use tokens in client-side JavaScript or mobile apps
  • HTTPS only: always call the API over HTTPS
  • One token per purpose: create a separate token for each integration so you can revoke one without affecting the others
  • Log your own API calls: keep a record in your integration for security auditing
  • Rotate regularly: create new tokens and delete old ones before they expire

Common Security Mistakes to Avoid

  • Committing tokens to GitHub or other public repositories
  • Sharing tokens by email, Slack, or other messaging apps
  • Using the same token across multiple projects
  • Storing tokens in plain-text files on shared servers
  • Including tokens in client-side code or browser applications
  • Leaving unused tokens active

Plan Requirements

Plan Availability

  • Individual Plan ($19 one-time): API access included
  • Agency Plan ($49 one-time): API access included
  • Free Plan: no API access - the Integrations page shows an upgrade banner instead of the Manage API Keys button

Upgrading for API Access

  1. Go to Settings → Plan.
  2. Click Upgrade for $19 one-time to see the plans, then choose the Individual Plan or the Agency Plan. Both are one-time purchases with lifetime access and a 60-day refund guarantee.
  3. Once the upgrade is applied, go to Settings → Integrations → Manage API Keys to create tokens.

See How to Upgrade Your BreezeDoc Plan for the full steps.

Rate Limits

  • Limit: 60 API requests per minute per user account (all of your tokens share it)
  • Headers: every response includes X-RateLimit-Limit and X-RateLimit-Remaining; a rate-limited response also includes Retry-After and X-RateLimit-Reset
  • Exceeded: the API returns HTTP 429 Too Many Requests
  • Best practice: back off and retry after the time in Retry-After

Creating and sending documents and invoices have their own, lower limits - see API Authentication and Rate Limits: Tokens, OAuth and Errors.

Troubleshooting

I cannot find API Settings or the Personal Access Tokens section

  • API access requires the Individual Plan or the Agency Plan. See which plan you are on under Settings → Plan.
  • On the Free Plan, the Integrations page shows an upgrade banner instead of Manage API Keys.
  • If you just upgraded, reload the page.

I get 401 Unauthorized when using my token

  • Check that you copied the whole token, without extra spaces or line breaks.
  • Use the exact header format: Authorization: Bearer YOUR_TOKEN.
  • Check that the token has not been deleted, and that it is less than one year old.
  • Confirm your plan still includes API access.

I lost my token after creating it

  • A token is shown only once and cannot be retrieved later.
  • Delete the old token and create a new one, then store it in a password manager.

I accidentally committed my token to GitHub

  • Delete the exposed token in API Settings right away and create a new one.
  • Remove the token from your Git history (for example with BFG Repo-Cleaner) and turn on GitHub secret scanning alerts.

My token works locally but fails in production

  • Check that the token is set correctly in the production environment variables, without extra whitespace.
  • Make sure the server can reach breezedoc.com over HTTPS (not blocked by a firewall).

Still stuck? Email support@breezedoc.com.

Frequently Asked Questions

How many personal access tokens can I create?

There is no limit on the number of tokens. Create only as many as you need, and delete the ones you no longer use.

Do personal access tokens expire?

Yes. A personal access token is valid for one year from the day you create it. Create a new token and update your integration before the old one expires.

Can I see my token again after creating it?

No. For security, the token is shown only once, when you create it. If you lose it, delete it and create a new one.

What is the difference between personal access tokens and OAuth 2.0?

A personal access token gives your own scripts access to your own account. OAuth 2.0 is for applications that other BreezeDoc users connect to their accounts.

Will my token keep working if I change my plan?

If you downgrade to the Free Plan, API access is disabled and your tokens stop working. After upgrading from the Free Plan to the Individual or Agency Plan, you can create and use tokens right away. Moving from the Individual Plan to the Agency Plan does not affect existing tokens.


Need more help? Contact our support team at support@breezedoc.com - we are here to help!

Related Articles