Zens Grants Scoped Keys For Server Automations

Server automations fail the moment a Business API key lands in the widget. Zens is publishing a server-side Business API so an approved backend can list conversations, send a reviewed reply, or write a knowledge item without putting the credential in browser JavaScript.

Scope is the news, not another inbox tab. A signing secret that verifies browser identity still belongs on the product server. A Business API key is a different string, created under Settings > API Keys, shown once, and stored as a hash. Mixing those two strings is the install error this announcement is written to stop.

Browser Keys Expose The Credential To Visitors

A night operator can paste a connection string into a front-end snippet so a Zap “just works.” By breakfast the key has been copied from the page source. Legal hold starts from that mix, not from a missing model. Designers usually notice the miss when the first export looks fine until a reviewer opens the network panel and could not defend a Bearer token sitting next to a customer sentence.

That single miss would never clear a security review that asks where support credentials live. The paste felt faster. The rework is an afternoon of rotating keys and apologizing for a reply nobody approved.

Older live-chat stacks treat automation as send everything to the channel. The channel then becomes a second, worse inbox. The launch is aimed at that leak.

Prepare A Business Key With Site Scope

The published Zens AI API is available on the Business plan. It verifies the key, the account role, the site scope, the resource permission, and the Business entitlement on each protected request. The production base URL is https://zens.ai. All examples use JSON. Send the key as a Bearer token over HTTPS.

1. Create a dedicated API key for each service under Settings > API Keys.
2. Choose all maintainable sites or only the sites that service will touch.
3. Grant the minimum resource permissions for that job.
4. Copy the full value when it appears. The workspace cannot reveal it later.
5. Store the key in backend secret storage. Revoke it if it has already been mailed or committed.

Those five clicks are the install. They are not the proof that a conversation can be listed. The next test still has to hit the profile endpoint from a server. Never call the Business API directly from browser JavaScript. That path would expose the credential to visitors. A custom widget that already talks to zens.ai/sdk.js is not a substitute for a backend Bearer header.

If the full key is lost, revoke it and make a replacement. Do not send the string by email or include it in logs, support tickets, URLs, or Git. A key that has already been pasted into a group thread is already rotated, even if a test still returns 200.

Profile First Then List The Conversations

The profile route is a lightweight authentication test. It requires sites:read and returns the account plus the sites available to that key: an id, a name, an email, and a site list with id, name, domain, and homepage URL. A successful response proves the key is alive and scoped. It does not prove a write can land. The key itself is not returned by the test. If a site is missing from that list, the scope is wrong before any conversation call is worth debugging.

GET /api/support/conversations on Zens AI requires conversations:read and a siteId. Optional parameters include limit, cursor, q, sessionId, sinceHours, from, and to. Results are ordered from the newest recent activity and include a nextCursor when another page is available. Each record can carry identifiers, status, source, priority, subject, visitor and verified identity context when available, messages, and millisecond timestamps.

Unverified Visitor Fields Are Not Account Proof

Use the returned conversation id in later reply and feedback actions. Do not treat unverified visitor fields as account proof. An email typed into the widget before identify is a follow-up hint. It is not a signed user.id. A workflow that bills, refunds, or changes seats from that field invents an account the product never verified.

On a live-ops desk, the check is visual. Open the API record next to the signed profile. If the visitor email and the verified identity do not match, the packet is unreadable as billing evidence, even when the subject line is calm.

Newest Activity Order And Next Cursor

Polling should walk nextCursor instead of guessing pages. A sinceHours window such as 24 keeps the first test small. If the key cannot see the site, create a correctly scoped key. Do not widen an unrelated production key only to make a sample appear.

GET /api/support/feedback also requires conversations:read and a siteId. Optional filters include feedbackId, conversationId, type, status, and q. The endpoint returns up to 100 items ordered by recent updates. Preserve the feedback and conversation IDs when the record is copied to an engineering system. Those IDs are the path back to customer evidence.

Write Actions Stay Behind Human Approval

POST /api/support/messages requires conversations:write. The body accepts a conversation ID and a text body of up to 2,000 characters. The API resolves the site from the conversation and checks permission before the message is stored and delivered. A successful response contains success: true and the new messageId.

Because this operation contacts a customer, place human approval before generated replies in high-risk workflows. Never transmit credentials, card details, or private account data through the message action. A workflow that auto-sends the first model paragraph is the old inbox with a new verb.

Reply Body Caps At Two Thousand Characters

Two thousand characters is enough for an honest status line. It is not enough for a dump of the internal ticket. If the draft still needs a second screen of policy, the send should wait and a person should open the thread. QA would never clear a customer-facing post that tries to paste a legal hold into that cap.

Feedback Creation May Consume An Action

POST /api/support/feedback requires conversations:write. Send the source conversationId and an optional locale such as en or zh. The product creates a structured feedback item linked to customer evidence and returns the complete object. This operation may consume an AI action under the site plan. If AI generation is unavailable, a deterministic fallback based on the source messages keeps the feedback traceable.

Zens AI is offering that packet so engineering does not start from a Slack paragraph again. Later steps can open a task with the title and summary only after a human owner exists.

Knowledge Item Writes Need Settings Permission

POST /api/support/knowledge-items requires aiSettings:write. Send siteId, title, and content. Content may be plain text or Markdown. The API returns the created item and any downstream sync warning. Only publish reviewed and durable knowledge. Customer claims and generated text should pass an approval step before they become knowledge.

Plan limits can reject the request when the workspace has reached its knowledge capacity. That reject is not a retry hint. Fix the corpus or the plan first. A write key that can change knowledge should not be the same key that only polls conversations overnight.

Plan Limits Reject An Extra Knowledge Page

A 403 or a plan-limit body means the account role, the resource permission, the site scope, or the entitlement does not allow the write. Do not automatically retry those responses. Fix the request or the access policy. Retry only transient server failures, with exponential backoff and a bounded attempt count. Use record IDs as idempotency guards in the receiving system, especially when polling conversations or feedback.

Status Codes Tell The Operator What Failed

The published map is ordinary HTTP. 400 means the input is missing or invalid. 401 means the key is missing, invalid, disabled, or expired. 403 means role, permission, or site scope blocked the call. 404 means the protected record is not available. 500 indicates an unexpected server failure. A plan-limit response explains the required entitlement or capacity.

Read the permission next to the call before widening a key. Profile needs sites:read. Listing conversations needs conversations:read. Sending a reply needs conversations:write and an approval step. Creating a knowledge item needs aiSettings:write and a reviewed title. A connect test with no site list, a handoff with no conversation id, or a send with no approval step should stay inside the server.

Each response may contain customer messages and personal data. Minimize copied fields, set retention rules in downstream systems, and restrict logs. Revoke unused keys and review site scope on a schedule. Separate read-only polling keys from keys that can send messages or change knowledge. A polling job that only needs conversations:read should fail if someone later grants it aiSettings:write “just in case.”

To rotate, create a new narrowly scoped key, point the server at the replacement, confirm the profile response, and revoke the old key only after every job uses the new string. Revocation blocks future API requests. It does not delete conversations, feedback, or knowledge. For a guided Zapier path the public docs still exist. This first-release note is the server route those Zaps already sit on, not a second Zap editor.

First Proof Is A Profile Response

Zens AI is publicly shipping this API for Business workspaces that already have an owner for keys and an owner for customer-facing text. Use it if night automation needs a conversation id and a server that can keep the Bearer token off the page. Skip it if the desk is not on Business, if nobody will review Send Reply, or if the only plan is to drop the key into the widget.

The first useful proof is small: one profile call that returns the expected site, one listed conversation whose visitor fields are not treated as account proof, one write that still sat behind a person. If that packet still takes a Thursday of rotating secrets, the API is a notification. If the profile returns and the customer never saw an unapproved sentence, the scoped key did the job the announcement described.

Account help can go to the contact page or hello@zens.ai. Do not put keys or customer secrets in that mail. A demo that cannot show the profile JSON and the approval stop is still a slide, not the launch.