API keys and the public API
Create a least-privilege public API key, make a first read, and recover safely from limits or delivery uncertainty.
- Who uses it
- Administrators
- Content updated
- 2026-09-09
Sign in to your company workspace first. Add the /app/… paths below to your company system URL.
Before you start
- An administrator account and a signed-in deployment domain
- The public API runtime switches enabled; pooled deployments additionally need Max or Enterprise entitlement
- An existing source, or access to Create or manage sources
Steps
Open the right guide and source
Open your own deployment domain at /app/int/docs?section=api&lang=en or /app/int/docs?section=api&lang=zh. In Developer center → API keys, use the existing source selector. If there is no source, choose Create or manage sources and finish source setup first. The default /app/int/docs page remains the legacy ingest guide.
Expected result: You are configuring the public API against the intended source, not the legacy ingest path.
Issue the least-privilege key
Key administration is administrator-only. Keys issued in this workspace explicitly enable the public API; start with customers.read and add only the scopes required for the job. An empty team or inbox restriction adds no restriction in that dimension; existing scope and tenant boundaries still apply. An old ingest key does not automatically gain public API access.
Expected result: The key can read only the intended tenant data and scoped resources.
Copy and protect the secret
Copy the secret once and put it in protected server configuration. Never embed it in public browser application code, URLs, screenshots or logs. PublicApi true does not isolate the key from ingest; customers.write may also authorize ingest. Revoke the key immediately if it is exposed, then issue a replacement with the same least-privilege review.
Expected result: The secret has a recoverable storage and revocation path.
Make the first read request
After issuing a read key, use Test read request to call the displayed parameter-free GET with that key. Inspect the actual data and meta response. You can also copy the scope-specific request into your server terminal; the public API reference contains request and response examples. Hide the secret after saving it.
Expected result: The first response confirms the key works and shows the resources it can access.
Page through results and honor limits
Pagination defaults to 50 and is capped at 100; pass meta.nextCursor until it is null. Runtime configuration and rate-limit headers are authoritative: defaults are 60 requests per key per minute and 600 per tenant per minute. On 429, honor Retry-After. IDs are strings and timestamps are UTC ISO.
Expected result: The client can continue from a cursor without exceeding the deployment’s current limits.
Send safely and verify delivery
Text sends require an 8–64 character Idempotency-Key and the same key for the same request. Accepted or queued means accepted for processing, not channel delivery; check message status or webhooks. Do not run an automatic write test; the optional Test read request only performs a GET without resource-ID path parameters.
Expected result: Retries are bounded and duplicate sends are avoided without treating acceptance as delivery.