API setup

Authentication and tenant scope

API requests are authenticated with either the signed-in application session or an account-scoped API key. API keys are managed from API keys after sign-in and should be scoped to the smallest role needed for the integration.

Every protected mutation is evaluated against the current account and tenant context. Do not reuse keys across customers, websites, staging, and production environments.

Rate limits and idempotency

• Respect `429` responses and retry only after the indicated recovery window or your own backoff policy.
• For retryable creates or webhook-style operations, use stable idempotency identifiers where the endpoint contract supports them.
• Do not parallelize account mutations unless the workflow can tolerate conflicts, duplicate prevention, and delayed webhook processing.

Errors

Validation errors return field-specific details. Authentication, authorization, tenant mismatch, rate-limit, conflict, and not-found states are distinct so callers can recover without guessing or exposing private records.

For operational failures, log the HTTP status, route, correlation data available to your caller, and sanitized response body. Never log raw API keys, password fields, OAuth tokens, or webhook signatures.