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
`agents`	read, write	Agent information and settings
`businesses`	read, write, delete	Business profiles, offerings, and online and physical presences
`contacts`	read, write, delete	Contacts and their addresses, emails, and phone numbers
`customers`	read, write, delete	Customer records and their transactions
`domains`	read, write	Domains, subdomains, DNS records, and registrations
`emailTemplates`	read, write, delete	Email templates
`emailTemplates.optIns`	read, write	Record and withdraw recipients’ marketing opt-ins
`invoices`	read, write, delete	Invoices and their line items
`invoices.payments`	read, write, delete	Invoice payment records
`organizations`	read, write	Business settings and membership
`properties`	read, write, delete	Custom property definitions and values
`users`	read, write	User accounts and profiles

No scope grants access to the automations, files, folders, messages, or tasks endpoints; API keys get 403 Forbidden there.

Permission inheritance

A scope on a resource also covers its child resources, which a 403 response can name in details.required.resource:

contacts covers contacts.addresses, contacts.emails, and contacts.phones
customers covers customers.transactions
businesses covers businesses.offerings, businesses.online_presences, businesses.physical_presences, and businesses.profile
emailTemplates covers reading emailTemplates.optIns, but not recording or withdrawing opt-ins — grant emailTemplates.optIns:write for that
invoices covers invoices.payments

HTTP methods and permissions

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

Reading an invoice returns its line items with invoices:read. Adding, changing, or removing a line item on a draft invoice requires invoices:read and invoices:write, not invoices:delete. Creating an invoice requires businesses:read, customers:read, invoices:read, and invoices:write. Deleting an invoice requires invoices:read, invoices:write, invoices:delete, invoices.payments:read, invoices.payments:write, and invoices.payments:delete. Deleting a contact, customer, or a record that belongs to a contact, customer, or business requires read, write, and delete on that resource. For example, deleting a contact’s phone number requires contacts:read, contacts:write, and contacts:delete, and deleting a business offering requires businesses:read, businesses:write, and businesses:delete. Deleting a customer transaction also requires invoices.payments:read and invoices.payments:write, because any invoice payment recorded against it is unlinked from it. API keys can’t delete domains, subdomains, or DNS records: there is no domains:delete scope. Delete them in the dashboard instead — see Delete or transfer a domain. Creating or updating an email template requires emailTemplates:read and emailTemplates:write. Deleting one requires emailTemplates:read, emailTemplates:write, and emailTemplates:delete. Listing and getting opt-ins requires emailTemplates.optIns:read. Recording or withdrawing an opt-in requires emailTemplates.optIns:read and emailTemplates.optIns:write. Opt-ins can’t be deleted, so there is no emailTemplates.optIns:delete scope. Listing and getting property definitions requires properties:read. Creating or updating one requires properties:read and properties:write. Retiring one with DELETE requires properties:read, properties:write, and properties:delete. Property values on a contact, customer, or business also require read on that resource. For example, listing a contact’s properties requires properties:read and contacts:read; setting or updating a value adds properties:write; deleting one adds properties:write and properties:delete. Writing a value doesn’t require write on the contact, customer, or business.

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 September 27, 2026

API Documentation

Agent resources

Automations

Businesses

Contacts

Customers

Domains

Email Templates

Files

Invoices

Invoice Line Items

Invoice Payments

Messages

Operations

Properties

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