API Key Management

API keys allow external applications and scripts to access your Bizzy organization 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 specifies:

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

Common Permission Patterns

Read-Only Access

{
    "contacts": { "read": true, "write": false, "delete": false },
    "customers": { "read": true, "write": false, "delete": false }
}

Full Contact Management

{
    "contacts": { "read": true, "write": true, "delete": true }
}

Messaging Only

{
    "messages": { "read": true, "write": true, "delete": false }
}

Permission Inheritance

Permissions cascade to child resources. Granting access to contacts automatically includes:

contacts.emails
contacts.phones
contacts.addresses
contacts.tags
contacts.notes

You can override child permissions to restrict access further.

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 Revoked

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 Revoke
Confirm the action

Revoked keys cannot be restored. Any application using the revoked key will immediately lose access.

When to Revoke

Revoke API keys immediately when:

A key may have been compromised
An employee with key access leaves the organization
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

Compliance

Account

Agent resources

Prerequisites

Creating an API Key

API Key Format

Setting Permissions

Permission Structure

Common Permission Patterns

Permission Inheritance

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

​Common Permission Patterns

​Permission Inheritance

​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

Common Permission Patterns

Permission Inheritance

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