Skip to main content

What a browser visitor can do

A visitor on a page that uses a publishable key can start a session with an agent and talk to it. The session token the browser receives:
  • is valid for 15 minutes at most (900 seconds), and only for that one room;
  • can publish microphone audio and data, and subscribe to the room;
  • cannot publish anything other than the microphone, and cannot change its own metadata.

What a browser visitor cannot do

  • Use the key from an origin you did not list. The API rejects it with origin_not_allowed, and browsers block the response otherwise.
  • Call an agent outside the key’s access scope or agent allowlist. The API answers agent_not_found.
  • Identify themselves to the agent. end_user is ignored for publishable keys, because anything the browser sends could be forged. Only your server can vouch for who the caller is, using a secret key.
  • Create sessions without limit. Burst limits and a daily cap apply per key.

Protecting a publishable key

  • List only the origins you control, with their exact scheme, host and port.
  • Use Allowed agent ids to limit a key to the agents it needs.
  • Use a separate key per site or environment, so you can revoke one without touching the others.
  • Know the daily cap: each key allows 2,000 sessions per day by default. Telzino support can adjust it for a key.
  • Revoke a leaked or unused key. It takes effect immediately.
Origin checks protect against other websites using your key in a visitor’s browser. They do not stop someone calling the API directly with a forged Origin header, which is why the rate limits and the daily cap exist. If a call is expensive or tied to a customer account, use a secret key on your server and decide there who may start it.

Metadata is background data

metadata and end_user give the agent background about the caller, such as a plan name or a customer id. They are data, not instructions. A metadata value that says “ignore your prompt” does not change how the agent is configured, and you should not rely on metadata to switch behavior that must be enforced. Anything a browser sends in metadata can be edited by the visitor, so do not put secrets in it and do not trust it for authorization. Metadata is limited to string values and 4096 bytes of JSON. For trustworthy caller details, mint the session on your server and pass end_user there.

Keep secrets on the server

Never put an OAuth client secret or an access token in browser code. If you need a server-minted session, build the endpoint described in Authentication and check your own user’s login before calling Telzino.