Personal Access Tokens for API Authentication

Personal Access Tokens (PATs) provide a simple way to authenticate with the BreezeDoc API. This guide covers creating, managing, and using personal access tokens for API access, along with security best practices and troubleshooting.

Prerequisites

  • Plan: Pro or Agency plan (API access not available on Free plan)
  • Account: Active BreezeDoc account with verified email
  • Access: Logged in to BreezeDoc dashboard
  • Browser: Modern web browser (Chrome, Firefox, Safari, Edge)

What are Personal Access Tokens?

Personal Access Tokens are long-lived authentication credentials that allow you to access the BreezeDoc API without using OAuth. They provide:

  • Simple Authentication – No complex OAuth flows required
  • Full Account Access – Tokens have the same permissions as your user account
  • Long-Lived – Tokens do not expire automatically
  • Revocable – Delete tokens anytime to revoke access
  • Multiple Tokens – Create separate tokens for different integrations

When to Use Personal Access Tokens

Personal Access Tokens are ideal for:

  • Personal Scripts – Automating your own workflows
  • Internal Tools – Building tools for your team or company
  • Testing – Quickly testing API endpoints during development
  • Server-to-Server – Backend integrations where you control both sides
  • Single User Access – Applications that only access your account

When NOT to Use Personal Access Tokens

Use OAuth 2.0 instead for:

  • Public Applications – Apps used by multiple BreezeDoc users
  • Third-Party Integrations – Applications you distribute to others
  • Client-Side Apps – Browser-based or mobile applications
  • Limited Permissions – When you need scoped access control

Creating a Personal Access Token

Step-by-Step Instructions

  1. Log in to your BreezeDoc account.
  2. Navigate to Settings ➜ Integrations ➜ API Settings.
  3. Scroll to the Personal Access Tokens section.
  4. Click Create New Token.
  5. In the modal, enter a descriptive Name for your token (e.g., "Production API Script", "Testing Environment", "Data Export Tool").
  6. Click Create.
  7. Your new token will be displayed in a modal with the message: "Here is your new personal access token. This is the only time it will be shown so don't lose it!"
  8. Copy the token immediately and store it securely (password manager recommended).
  9. Click Close when you have saved the token.

Token Naming Best Practices

Use descriptive names to identify each token's purpose:

  • Good examples: "Production Integration", "Development Testing", "Backup Script Server", "Analytics Dashboard"
  • Poor examples: "Token 1", "Test", "My Token"
  • Include environment: Specify if token is for production, staging, or development
  • Include purpose: Note what system or script uses the token

Using Personal Access Tokens

Authentication Header Format

Include your token in the Authorization  header of all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Example API Request

Using curl:

curl -X GET https://api.breezedoc.com/v1/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://api.breezedoc.com/v1/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://api.breezedoc.com/v1/me', headers=headers)
print(response.json())

Managing Your Tokens

Viewing Active Tokens

  1. Go to Settings ➜ Integrations ➜ API Settings.
  2. Scroll to Personal Access Tokens section.
  3. View list of all active tokens with their names.
  4. Token values are never shown again after creation.

Revoking (Deleting) Tokens

Revoke tokens that are no longer needed or may be compromised:

  1. Go to Settings ➜ Integrations ➜ API Settings.
  2. Find the token in the Personal Access Tokens list.
  3. Click Delete next to the token name.
  4. The token is immediately revoked and can no longer be used.
  5. All API requests using this token will return 401 Unauthorized errors.

When to Revoke Tokens

  • Token Exposed: If a token is accidentally committed to a public repository, shared, or exposed
  • Project Ended: When a project or integration using the token is decommissioned
  • Security Rotation: As part of regular security hygiene (rotate tokens every 3-6 months)
  • Employee Departure: When team members with token access leave
  • Suspicious Activity: If you notice unusual API usage or 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 in password managers for long-term secure storage
  • Use secrets management tools in production (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Encrypt at rest if storing tokens in databases or configuration files

Safe Token Usage

  • Server-side only: Never use tokens in client-side JavaScript or mobile apps
  • HTTPS only: Always use HTTPS endpoints to prevent token interception
  • Minimize scope: Create separate tokens for different purposes
  • Monitor usage: Regularly review API activity in your account
  • Rotate regularly: Create new tokens and revoke old ones every few months

Common Security Mistakes to Avoid

  • ❌ Committing tokens to GitHub or public repositories
  • ❌ Sharing tokens via email, Slack, or other messaging platforms
  • ❌ 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 indefinitely

Plan Requirements and Limits

Plan Availability

Personal Access Tokens are available on:

  • Pro Plan ($19/month): ✅ API access included
  • Agency Plan ($49/month): ✅ API access included
  • Free Plan: ❌ API access not available

Upgrading for API Access

If you're on the Free plan and need API access:

  1. Go to Settings ➜ Billing ➜ Plans.
  2. Choose Pro or Agency plan.
  3. Complete payment setup.
  4. API access is enabled immediately after upgrade.
  5. Navigate to Settings ➜ Integrations ➜ API Settings to create tokens.

Troubleshooting

Issue: Cannot see API Settings or Personal Access Tokens section

Fix: API access requires Pro or Agency plan. Verify your plan in Settings ➜ Billing. If on Free plan, upgrade to Pro or Agency to enable API access. If recently upgraded, try logging out and back in to refresh permissions.

Issue: 401 Unauthorized error when using token

Fix: Verify you copied the complete token without extra spaces or line breaks. Ensure you're using the correct header format: Authorization: Bearer YOUR_TOKEN . Check that the token hasn't been deleted in API Settings. Confirm your plan still has API access enabled.

Issue: Lost my token after creation

Fix: Tokens are only shown once for security reasons. You cannot retrieve the token value again. You must delete the old token and create a new one. Use a password manager or secure storage for future tokens.

Issue: Accidentally committed token to GitHub

Fix: Immediately go to API Settings and delete the exposed token. Create a new token with a different value. Consider using git filter-branch  or BFG Repo-Cleaner to remove the token from Git history. Enable GitHub secret scanning alerts if using GitHub. Review your repository access logs for suspicious activity.

Issue: Token working locally but failing in production

Fix: Verify the token is correctly set in production environment variables. Check for extra whitespace or encoding issues in environment variable values. Ensure production server can reach api.breezedoc.com (not blocked by firewall). Verify HTTPS is being used, not HTTP.

Rate Limits

All Personal Access Tokens are subject to API rate limits:

  • Limit: 60 requests per minute per account
  • Headers: Rate limit information included in response headers (X-RateLimit-Limit , X-RateLimit-Remaining , X-RateLimit-Reset )
  • Exceeded: Returns HTTP 429 Too Many Requests
  • Best Practice: Implement exponential backoff and respect rate limit headers

FAQ

Q: How many Personal Access Tokens can I create?

A: There is no hard limit on the number of tokens. However, it's recommended to create only as many as you need and revoke unused tokens for security.

Q: Do Personal Access Tokens expire?

A: No, tokens do not expire automatically. They remain valid until you delete them or your account is closed. For security, consider rotating tokens every 3-6 months.

Q: Can I see my token value after creation?

A: No, for security reasons, the token value is only displayed once when you create it. If you lose the token, you must delete it and create a new one.

Q: What's the difference between Personal Access Tokens and OAuth 2.0?

A: Personal Access Tokens provide full account access with a single token, ideal for personal scripts and internal tools. OAuth 2.0 is designed for applications that access multiple users' accounts, with scoped permissions and token refresh capabilities. Use PATs for personal use, OAuth for public applications.

Q: Can I use Personal Access Tokens in client-side JavaScript?

A: No, never use PATs in client-side code (browsers, mobile apps). Tokens would be exposed to users, creating a security risk. Use PATs only in server-side code where they can be kept secure.

Q: Will my token work after I upgrade or downgrade my plan?

A: If you downgrade to Free plan, API access is disabled and all tokens stop working. If you upgrade from Free to Pro/Agency, you can immediately create and use tokens. Upgrading between Pro and Agency does not affect existing tokens.


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