Auth and Scopes

Current V2 status (2026-09-24): API keys, scopes, live and test modes, rate limits, and request logs below are live in V2. Members need the manage integrations permission to open the page. The webhooks:read and webhooks:write scopes cover /api/v1/webhooks (live keys only); inbound automation webhook intake remains V1-only. Automation workflow API routes and scopes below are available to eligible live keys.

External API requests authenticate with API keys created in Settings > Integrations > External API keys.

CE Pro shows the raw secret only once when you create the key. After that, the key is stored as a one-way hash and cannot be recovered.

Key Formats

• Live keys begin with ce_live_
• Test keys begin with ce_test_

Send the key in the Authorization header:

Authorization: Bearer ce_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx

Where To Manage Keys

From the API Keys settings page you can:

• Create a key
• Choose live or test mode
• Limit the key to specific scopes
• Set a per-minute rate limit
• Add an optional expiration date
• Review request logs
• Update or revoke a key later

The API key forms now validate the full payload before saving. A key needs at least one scope, the environment must be either live or test, the per-minute rate limit must be a positive whole number, and malformed expiration values are rejected instead of creating a partial key record.

When you revoke a key from the settings UI, the row now flips to its revoked state immediately instead of waiting for a full page refresh. That helps office staff confirm the key is no longer active before they leave the screen.

Troubleshoot API key settings access

Opening Settings > Integrations > External API keys requires the manage_integrations application permission. If an owner cannot open the page, ask an administrator to check the effective permission and whether both the organization and member permission records have completed the supported permission migration. Older permission records may need that migration before the permission is available. A role label or feature flag alone does not grant manage_integrations or bypass the page's permission checks. API key scopes authorize API requests; they do not grant access to the settings page.

Available Scopes

• leads:read
• leads:write
• clients:read
• clients:write
• estimates:read
• estimates:write
• jobs:read
• jobs:write
• invoices:read
• invoices:write
• webhooks:read
• webhooks:write
• workflows:read
• workflows:write

The estimates:write scope is required for the new live-key draft-creation route, which is pending production. It grants creation of an empty draft only; it does not allow the key to price, send, accept, or charge for an estimate. The key's creator must also be active and have access to the requested location.

In V1, webhooks:write covers both outbound webhook destination management under /api/v1/webhooks and inbound automation webhook intake at /api/automations/webhooks/inbound; both flows use the same shared API-key rate limiting.

Application workflow scopes

The application workflow gateway uses exact, explicit scopes:

• workflows:read for catalog and schema discovery and query operations;

receipt lookup accepts this scope or workflows:write

• workflows:write for mutation operations and their idempotent retries

These routes accept live keys only. A test key cannot call them. The key creator must remain an active member, and every operation checks that member's current application permissions. The key's location scope must cover the creator's complete current location scope. Choosing an API scope does not grant the matching application permission.

Existing keys do not receive these scopes automatically. Neither the legacy global * scope nor workflows:* grants access; add the exact workflow scope to the key in Settings > Integrations > External API keys. Query and mutation operations can also have their own permission and location checks.

Legacy automation workflow scopes

The automation workflow API uses these scopes:

• automations:read to list and read existing workflows
• automations:write to save a draft, publish a selected draft revision, or

pause an existing workflow

These routes accept live keys only. A test key cannot call them, including for reads. The active, web-capable member who owns the key needs effective view_automations or manage_automations permission to read workflows, and manage_automations to write. Both the member and the key must have organization-wide location access.

Named scopes are not added to existing keys automatically. The existing automations:* and * wildcard scopes also match these routes, subject to the same member, key, and organization-wide access checks. MCP uses the same scopes and bearer-key format; no OAuth flow or new key type is added.

Wildcard scopes are supported:

• leads:*
• clients:*
• estimates:*
• jobs:*
• invoices:*
• webhooks:*
• *

Live Vs Test Behavior

Live keys are meant for real customer and revenue workflows.

Test keys are meant for integration development. They continue to:

• Test keys can read only test records.
• Test keys can write only to leads, clients, and estimates.
• Test keys cannot create jobs, invoices, or webhook destinations.
• Test writes are isolated from normal admin views and operational workflows.

Proposal and reporting resources are not part of the shipped V1 public surface, so the V1 contract does not issue separate public scopes for them.

Rate Limits

Each key has its own per-minute rate limit. The default is 60 requests per minute, but you can raise or lower it per key.

Request-log views also validate their page-size input now, so the admin log panel only accepts limits from 1 to 200 rows per request.

Every response includes:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

If a key exceeds its allowance, CE Pro returns 429 Too Many Requests plus Retry-After.

If the shared rate-limit backend is temporarily unavailable, CE Pro fails closed and returns 503 rate_limit_unavailable instead of silently skipping protection.

Live and test keys are validated against their exact key prefix and environment. A ce_live_* key cannot be replayed as ce_test_*, and vice versa.

Common Auth Errors

• 401 invalid_api_key: the header is missing, malformed, expired, or revoked
• 403 insufficient_scope: the key does not include the required scope
• 403 unsupported_in_test_mode: the endpoint is not available to test keys in v1
• 429 rate_limited: the key exceeded its current minute window
• 503 rate_limit_unavailable: CE Pro could not verify rate limits safely

Best Practices

• Create separate keys per integration, not one shared key for everything.
• Start with the narrowest scopes possible.
• Use test keys during development.
• Revoke keys instead of reusing them after a partner changes ownership.
• Store keys in your secret manager or deployment platform, never in frontend code.