Docs/Workspace API/Scopes

Scopes

Scopes control what an API key can do. They are chosen at key-create time and cannot be changed later. rotate the key to change scopes. Start with the least-privilege scope set that your integration needs.

Available scopes

Scope	Grants
crm.contacts.read	List and retrieve CRM contacts
crm.contacts.write	Create and update CRM contacts
crm.contacts.delete	Soft-delete CRM contacts (30-day recycle bin, restore possible)
crm.companies.read	List and retrieve CRM companies
crm.companies.write	Create and update CRM companies
crm.companies.delete	Soft-delete CRM companies (30-day recycle bin, restore possible)
crm.deals.read	List and retrieve CRM deals
crm.deals.write	Create and update CRM deals
crm.deals.delete	Soft-delete CRM deals (30-day recycle bin, restore possible)
crm.tasks.read	List and retrieve CRM tasks
crm.tasks.write	Create, update and complete CRM tasks
crm.tasks.delete	Soft-delete CRM tasks (30-day recycle bin)
crm.notes.read	List and retrieve CRM notes
crm.notes.write	Create and update CRM notes
crm.notes.delete	Soft-delete CRM notes (30-day recycle bin)
crm.segments.read	List and retrieve CRM segments
crm.segments.write	Create/update segments, manage static-segment membership
crm.segments.delete	Soft-delete CRM segments (30-day recycle bin)
sales.quotes.read	List and retrieve sales quotes
sales.quotes.write	Create, update, send and cancel sales quotes
sales.quotes.delete	Soft-delete sales quotes (30-day recycle bin, restore possible)
sales.invoices.read	List and retrieve sales invoices
sales.invoices.write	Create, update, send, mark paid, void, credit-note and send reminders on invoices
sales.invoices.delete	Soft-delete draft invoices only (30-day recycle bin, restore possible)
sales.products.read	List and retrieve products in the sales catalog
sales.products.write	Create and update products
sales.products.delete	Soft-delete products (30-day recycle bin, restore possible)
bookings.entries.read	List and retrieve Advanced Booking entries
bookings.entries.write	Create, update and change status on bookings
bookings.entries.delete	Soft-delete bookings (30-day recycle bin)
bookings.customers.read	List and retrieve Advanced Booking customers
bookings.customers.write	Create and update booking customers
bookings.customers.delete	Soft-delete booking customers (30-day recycle bin, GDPR-anonymized rows preserved)
webhooks.read	List webhook endpoints and delivery logs (via /api/caller/webhooks)
webhooks.write	Create, update, and delete webhook endpoints (via /api/caller/webhooks)

Meta-scopes

Wildcards let you grant broader access without listing every scope. Match by module or action.

Meta-scope	Grants
*	Grants everything. Use with caution. audit the key regularly.
crm.*	Grants all crm.* scopes (contacts + companies + deals + tasks + notes + segments, read + write + delete)
sales.*	Grants all sales.* scopes (quotes + invoices + products, read + write + delete)
bookings.*	Grants all bookings.* scopes (entries + customers, read + write + delete)
*.read	Grants every .read scope across modules. safe for reporting integrations
*.write	Grants every .write scope
*.delete	Grants every .delete scope (destructive — audit key usage regularly)
crm.contacts.*	Grants read + write + delete for one specific resource. Any resource pattern works.

Scope-check errors

When a request needs a scope that the key doesn't grant, we return:

HTTP 403 Forbidden
{
  "error": {
    "type": "permission_denied",
    "code": "SCOPE_INSUFFICIENT",
    "message": "This API key is missing required scope: crm.contacts.write",
    "param": "crm.contacts.write"
  }
}

Recommended scope patterns

Website form → CRM

crm.contacts.write

Only creates contacts. Can't read your CRM data if compromised.

BI / reporting tool

*.read

Read-only across all modules. Safe for analytics pulls.

Full-sync CRM integration (e.g. Zapier)

crm.*

CRUD on contacts, companies and deals. Excludes sales/marketing/bookings.