API Key Management

API keys allow external applications and scripts to access your Bizzy business programmatically. This guide covers creating, configuring, and securing your API keys.

This guide covers API keys for REST API access. AI agents (Claude, Cursor, Windsurf, etc.) connect through the MCP server, which uses its own authentication flow rather than API keys.

Prerequisites

You must be an Owner to manage API keys
Admins and Users cannot create, view, or revoke API keys

Creating an API Key

To create a new API key:

Navigate to Settings > Security > API Keys
Click Create API Key
Enter a descriptive name (e.g., “Production CRM Integration”)
Configure permissions (see below)
Optionally set an expiration date
Click Create

The full API key is displayed only once after creation. Copy it immediately and store it securely. You cannot retrieve the full key later.

API Key Format

Bizzy API keys are prefixed with sk_ followed by a long random secret:

sk_a1b2c3...

sk_ - Indicates a secret key
Followed by a unique random string

For security, Bizzy stores only a hash of each key — never the key itself. After creation, the full key is shown once; the dashboard thereafter displays a masked preview (the sk_ prefix plus the last four characters, e.g. sk_a1b…c3d4) so you can identify a key without exposing it.

Setting Permissions

API keys support fine-grained permissions that control which resources the key can access and what actions it can perform.

Permission Structure

Each permission pairs a resource with an access level:

Component	Description	Example
Resource	What the key can access	`contacts`, `domains`
Action	What operations are allowed	`read`, `write`

For each resource, leave it at None or enable Read, Write, or both. businesses, contacts, customers, emailTemplates, invoices, invoices.payments, and properties also offer Delete.

Available Resources

Resource	Covers
`agents`	Agent information and settings
`businesses`	Business profiles and settings
`contacts`	Contact information and details
`customers`	Customer records and sync state
`domains`	Domain registrations and DNS settings
`emailTemplates`	Email templates and their versions
`emailTemplates.optIns`	Recipients’ marketing email opt-in records
`invoices`	Invoice headers, line items, and totals
`invoices.payments`	Manual invoice payment records
`organizations`	Business settings and membership
`properties`	Custom property definitions and values
`users`	User accounts and profiles

Read on Email Templates includes reading Marketing Opt-ins, but Write doesn’t include writing them. For a key that records or withdraws opt-ins, enable Read on Email Templates or Marketing Opt-ins, and Write on Marketing Opt-ins. To delete records, enable Read, Write, and Delete on the resource — for example, all three on Contacts to delete contacts and their addresses, emails, and phone numbers. Deleting customer transactions also takes Read and Write on Invoice Payments. Domains has no Delete: delete domains and DNS records in the dashboard. To delete property definitions, enable Read, Write, and Delete on Properties. To read or set property values on contacts, customers, or businesses, also enable Read on that resource — for example, Read and Write on Properties plus Read on Contacts to set contact properties.

Common Permission Patterns

Read-only reporting key — enable Read on contacts and customers. Full contact management — enable both Read and Write on contacts. Domain automation — enable Read and Write on domains only. Grant the narrowest set that the integration needs; anything you do not explicitly enable is denied.

Key Expiration

Set an expiration date to automatically disable API keys after a certain period:

Use Case	Recommended Expiration
Temporary integrations	7-30 days
Contractor access	Project duration
Production integrations	90-365 days
Internal tools	No expiration (rotate manually)

Expired keys return a 401 Unauthorized error. Create a new key before the old one expires to avoid service interruption.

Monitoring Key Usage

Track API key activity from the API Keys dashboard:

Metric	Description
Key	Masked preview (`sk_…last4`) to identify the key
Last Used	Timestamp of the most recent API call
Created	When the key was created
Expires	Expiration date (if set)
Status	Active, Expired, or Never expires

Use the “Last Used” timestamp to identify unused keys that should be revoked.

Revoking Keys

To revoke an API key:

Navigate to Settings > Security > API Keys
Find the key to revoke
Click Delete
Confirm the action

Deleted keys cannot be restored. Any application using the key loses access immediately.

When to Revoke

Revoke API keys immediately when:

A key may have been compromised
An employee with key access leaves the business
An integration is decommissioned
A key hasn’t been used in 90+ days

Security Best Practices

Key Storage

Never commit API keys to version control
Use environment variables or secret management services
Restrict file permissions on configuration files containing keys

export BIZZY_API_KEY="sk_live_abc123..."

const apiKey = process.env.BIZZY_API_KEY;

import os
api_key = os.environ.get('BIZZY_API_KEY')

Key Rotation

Regularly rotate API keys to limit exposure from potential leaks:

Create a new key with the same permissions
Update your application to use the new key
Verify the new key works in production
Revoke the old key

Recommended rotation schedule:

Environment	Rotation Frequency
Production	Every 90 days
Development	Every 30 days
After incidents	Immediately

Principle of Least Privilege

Grant only the permissions each integration needs:

Read-only keys for reporting and analytics
Resource-specific keys for focused integrations
Separate keys for separate applications

Audit Regularly

Review your API keys monthly:

Remove unused keys (no activity in 90+ days)
Verify permissions match current requirements
Check expiration dates and rotate as needed

Troubleshooting

Common Errors

Error	Cause	Solution
`401 Unauthorized`	Invalid or expired key	Check key value and expiration
`403 Forbidden`	Insufficient permissions	Verify key has required resource/action
`429 Too Many Requests`	Rate limit exceeded	Implement backoff and retry logic

Debugging Permission Issues

If your API key returns 403 Forbidden:

Check the error response for the required permission
Compare against your key’s configured permissions
Update the key or create a new one with correct permissions

Next Steps

API Introduction

Learn how to use the Bizzy API

Authentication

Understand API authentication methods

Overview

Platform Admin

Account

Agent resources

Prerequisites

Creating an API Key

API Key Format

Setting Permissions

Permission Structure

Available Resources

Common Permission Patterns

Key Expiration

Monitoring Key Usage

Revoking Keys

When to Revoke

Security Best Practices

Key Storage

Key Rotation

Principle of Least Privilege

Audit Regularly

Troubleshooting

Common Errors

Debugging Permission Issues

Next Steps

API Introduction

Authentication

​Prerequisites

​Creating an API Key

​API Key Format

​Setting Permissions

​Permission Structure

​Available Resources

​Common Permission Patterns

​Key Expiration

​Monitoring Key Usage

​Revoking Keys

​When to Revoke

​Security Best Practices

​Key Storage

​Key Rotation

​Principle of Least Privilege

​Audit Regularly

​Troubleshooting

​Common Errors

​Debugging Permission Issues

​Next Steps

API Introduction

Authentication

Prerequisites

Creating an API Key

API Key Format

Setting Permissions

Permission Structure

Available Resources

Common Permission Patterns

Key Expiration

Monitoring Key Usage

Revoking Keys

When to Revoke

Security Best Practices

Key Storage

Key Rotation

Principle of Least Privilege

Audit Regularly

Troubleshooting

Common Errors

Debugging Permission Issues

Next Steps