Skip to main content
The Flowyte API has two authentication modes that both resolve to the same tenant-scoped identity, so a key can never reach another organization’s data.

​
Secret API keys (server-to-server)

For your backend and for agents building against the API, use a secret key:
Your API key already determines the organization — no extra headers are needed.
The first key is minted in the dashboard’s Developer page (a chicken-and-egg bootstrap). Manage your keys — mint, rotate, and revoke — in the dashboard Developer page.

​
Browser sessions

The dashboard authenticates with a session token. You won’t use this directly when building against the API — it’s how the builder UI talks to the same endpoints your key does.

​
Publishable keys (the chat widget)

The embeddable chat widget authenticates in the browser with a publishable key (flowyte_pk_…). It is agent-pinned, origin-allowlisted, and limited to public chat — safe to ship in client-side code.

​
Scopes

Secret keys carry scopes that gate which operations they can call. Request only what you need. Common scopes: The authoritative scope list is the Scope enum in the API Reference.
Message content lives under calls:read, not sms:read. Despite the name, calls:read is channel-agnostic: an SMS conversation is stored as a conversation like any other, so GET /conversations/{id}/transcript returns the verbatim text of every message a customer sent or received. A key holding calls:read can read all of it.sms:read is the compliance surface — registration status, number toggles, the opt-out list and the contact roster. It grants no message text. It does download text attachments: GET /sms/media/{id} returns a link to any picture, video or file (a PDF, for example) sent or received by text in your workspace, given its id. Those ids appear in transcripts, webhook deliveries and send receipts. Neither sms:read nor sms:send can read a conversation, but sms:send can attach any text attachment whose id it knows to a message it sends — including a picture a customer sent you. Only text attachments are reachable this way: a file a visitor uploaded in a web chat is not.Four consequences worth planning around:
  • A key granted “just call reads” can read your customers’ text messages.
  • A key with sms:read that knows (or is handed) an attachment id can download the picture or file behind it, and a key with sms:send can forward it. Treat attachment ids as you would the pictures themselves.
  • calls:read also grants the event receipt (GET /conversations/{id}/receipt) — the forensic record of everything the agent did on that call: tool calls, knowledge lookups, guardrail decisions and latency samples. Summary, transcript and receipt are one grant, not three.
  • There is currently no way to grant SMS visibility without also granting voice and chat; calls:read is all-or-nothing across channels.
Reading a conversation also needs analytics:read to find it in the first place — the list endpoint and the transcript endpoint are separately scoped, so a key with only analytics:read sees conversations listed but every transcript comes back empty. That is a missing scope, not a bug.
Some endpoints documented in the contract are reserved (planned ahead of release). Calling one returns a 403, not a 404. If a correctly-scoped call returns 403, check whether the endpoint is marked reserved.