Authentication

The Bizzy API uses API keys to authenticate requests. You can create and manage API keys from your organization settings in the dashboard.

Creating an API Key

Sign in to the Bizzy Dashboard
Navigate to Settings > API Keys
Click Create API Key
Give your key a descriptive name (e.g., “Production Server” or “Development”)
Select the permission scopes your key needs
Click Create and copy your key immediately

Your API key is only shown once when created. Store it securely - you won’t be able to see it again. If you lose your key, you’ll need to create a new one.

Using Your API Key

Include your API key in the Authorization header of every request using the Bearer token format:

Authorization: Bearer your-api-key

curl https://api.bizzyco.ai/v1/contacts \
  -H "Authorization: Bearer sk_live_abc123..."

const response = await fetch('https://api.bizzyco.ai/v1/contacts', {
    headers: {
        Authorization: 'Bearer sk_live_abc123...',
    },
});

const { data } = await response.json();

import requests

response = requests.get(
    'https://api.bizzyco.ai/v1/contacts',
    headers={
        'Authorization': 'Bearer sk_live_abc123...',
    }
)

data = response.json()['data']

Permission Scopes

API keys are scoped to specific permissions that control what resources they can access. When creating a key, grant only the permissions your integration needs.

Available Scopes

Resource	Actions	Description
`contacts`	read, write, delete	Manage contacts and their details
`customers`	read, write, delete	Manage customer records
`businesses`	read, write, delete	Manage business profiles
`messages`	read, write, delete	Access email, SMS, and voice messages
`automations`	read, write, delete	Configure automation workflows
`domains`	read, write, delete	Manage custom domains
`users`	read, write, delete	Manage user profiles and settings
`organization`	read, write, delete	Manage organization settings and members
`api_keys`	read, write, delete	Manage API keys and their permissions
`resources`	read, write, delete	Access shared resources and analytics

Permission Inheritance

Permissions follow a hierarchical model. Granting access to a parent resource also grants access to its child resources:

contacts includes contacts.emails, contacts.phones, contacts.addresses, contacts.tags, contacts.notes
customers includes customers.contacts
businesses includes businesses.details, businesses.tags, businesses.contacts, businesses.addresses
messages includes messages.email, messages.sms, messages.voice
automations includes automations.actions
domains includes domains.dns, domains.verification
users includes users.profile, users.settings
organization includes organization.settings, organization.billing
resources includes resources.analytics

HTTP Methods and Permissions

HTTP Method	Required Permission
GET	`read`
POST	`write`
PUT, PATCH	`write`
DELETE	`delete`

Authentication Errors

If authentication fails, you’ll receive a 401 Unauthorized response:

{
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid or missing API key"
    }
}

Common causes:

Missing Authorization header
Invalid or revoked API key
Malformed Bearer token (missing “Bearer ” prefix)

If your key lacks permission for a specific action, you’ll receive a 403 Forbidden response:

{
    "error": {
        "code": "INSUFFICIENT_PERMISSIONS",
        "message": "Missing write permission for contacts",
        "details": {
            "required": {
                "resource": "contacts",
                "action": "write"
            },
            "hint": "Contact your administrator to request additional permissions"
        }
    }
}

Security Best Practices

Never commit API keys to version control

Use environment variables or a secrets manager to store your API keys. Add .env files to your .gitignore.

# .env (never commit this file)
BIZZY_API_KEY=sk_live_abc123...

// Use environment variables
const apiKey = process.env.BIZZY_API_KEY;

Use separate keys for each environment

Create different API keys for development, staging, and production. This limits the blast radius if a key is compromised.

Grant minimum required permissions

Follow the principle of least privilege. Only grant the specific permissions your integration needs. A read-only dashboard doesn’t need write access.

Rotate keys regularly

Periodically create new API keys and deprecate old ones. This limits the window of exposure if a key is leaked.

Monitor API key usage

Review your API key activity in the dashboard regularly. Revoke any keys showing suspicious activity immediately.

Server-Side Only

API keys should only be used in server-side code. Never expose your API key in client-side JavaScript, mobile apps, or any code that runs in the browser.

If you need to access the Bizzy API from a client application, implement a backend proxy that handles authentication on behalf of your users.

Last modified on May 30, 2026

API Documentation

Agent resources

Automations

Businesses

Contacts

Customers

Domains

Files

Messages

Operations

Tasks

Creating an API Key

Using Your API Key

Permission Scopes

Available Scopes

Permission Inheritance

HTTP Methods and Permissions

Authentication Errors

Security Best Practices

Server-Side Only

​Creating an API Key

​Using Your API Key

​Permission Scopes

​Available Scopes

​Permission Inheritance

​HTTP Methods and Permissions

​Authentication Errors

​Security Best Practices

​Server-Side Only

Creating an API Key

Using Your API Key

Permission Scopes

Available Scopes

Permission Inheritance

HTTP Methods and Permissions

Authentication Errors

Security Best Practices

Server-Side Only