Auth and Scopes

External API requests authenticate with API keys created in Settings -> Integrations -> 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.

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

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

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. In v1:

• 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 current public v1 surface, so CE Pro does not issue separate public scopes for them yet.

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.