Keys and scopes

Every request carries an organisation API key as a Bearer token:

HTTP

Authorization: Bearer zq_live_…

A key belongs to one organisation and reaches only that organisation's data: an id from another organisation is 404 not_found. A key acts as an admin of its organisation, limited by its scopes; it is never an owner (see The organisation).

Make a key#

In the Zentiq console, open More → API Keys and choose Create a key:

Name it after where it will live ("Website", "CRM sync"), so you can tell your keys apart later.
What can it do? Pick a preset below, or Choose scopes to tick them one by one.
Create key, then copy it. It is shown once: Zentiq keeps only a fingerprint of it.

The developer API is part of every plan. When an organisation's plan doesn't include it, every call answers 403 upgrade_required with feature: "api.access".

A full-access key can also make keys with the API (POST /v1/keys), never with a scope it doesn't hold itself. The new key's secret is in that answer's key, once.

Presets#

Preset	For	Scopes
Read only	Reads the organisation's setup, sessions (numbers), results and usage. Changes nothing; no contacts, no conversation words.	avatars:readvoices:readpersonas:readduos:readwidgets:readknowledge:readportals:readcontent:readsessions:readresults:readassignments:readsettings:readevents:readusage:read
Website assistant	Builds a persona with knowledge, puts it on your website and follows up its leads, bookings and hand-offs.	avatars:readavatars:writevoices:readvoices:writepersonas:readpersonas:writeknowledge:readknowledge:writewidgets:readwidgets:writeportals:readportals:publishinbox:readinbox:writewebhooks:manageevents:read
CRM	Receives website leads, bookings and hand-offs, with contact details, and updates their status.	inbox:readinbox:writeevents:readwebhooks:manage
Hiring integration	Sets up screening roles, invites candidates from your ATS and records the hiring team's decisions.	portals:readportals:writeportals:publishcontent:readcontent:writecandidates:readcandidates:writewebhooks:manageevents:read
Chat escalation	Hands conversations from your text chat (Intercom, Zendesk or your own) to the video avatar, and nothing else.	escalations:write
People sync	Keeps units, members and learners in step with your HR or school system.	people:readpeople:write
Learning platform	Builds and publishes training portals, embeds them for your signed-in users, syncs people and reads results.	portals:readportals:writeportals:publishcontent:readcontent:writeembed:writepeople:readpeople:writesessions:readresults:readassignments:readassignments:writewebhooks:manageevents:read
Full access	Everything a key can do, except the sensitive scopes you add yourself (a candidate's data copy, interview content, case links, consent records).	* (full access)

Scopes#

A key holds the scopes it lists. Every operation in the reference names the scopes it needs, and a key without one of them gets 403 forbidden with a message naming it.

Scope	Grants	Notes
`avatars:read`	Read faces: the library, uploads and designs.	None
`avatars:write`	Upload, design and delete faces.	None
`voices:read`	Read voices.	None
`voices:write`	Clone and delete voices.	None
`personas:read`	Read personas (the avatars people talk to).	None
`personas:write`	Create, change and delete personas.	None
`duos:read`	Read the duo library and the organisation's duos.	Keys made before 2026-10-01 hold it through `personas:read`.
`duos:write`	Add duos from the library and publish them.	Keys made before 2026-10-01 hold it through `personas:write`.
`widgets:read`	Read a persona's website widget.	Keys made before 2026-10-01 hold it through `personas:read`.
`widgets:write`	Set up a persona's website widget (switching it on also needs portals:publish).	Keys made before 2026-10-01 hold it through `personas:write`.
`knowledge:read`	Read knowledge packs and their documents, and search them.	None
`knowledge:write`	Create and delete knowledge packs and documents.	None
`portals:read`	Read portals, subjects (their structure), doors and domains.	None
`portals:write`	Create and change portals, subjects, doors and domains.	None
`content:read`	Read subject content and its versions.	Keys made before 2026-10-01 hold it through `portals:read`.
`content:write`	Edit subject content (drafts) and subject documents.	Keys made before 2026-10-01 hold it through `portals:write`.
`portals:publish`	Publish portals and subject versions, open doors to visitors, switch a widget on.	Keys made before 2026-10-01 hold it through `portals:write`.
`embed:write`	Issue embed tokens for signed-in users of your own app.	Keys made before 2026-10-01 hold it through `portals:write`.
`customers:tokens`	Mint identity tokens for your website's signed-in customers (Actions), and nothing else.	None
`escalations:write`	Hand a text chat conversation to the video avatar (escalation links), and nothing else.	None
`connections:write`	Connect, test, list and disconnect your own systems (a calendar, a CRM, a shop, an MCP server) for Actions. Keys are write-only.	None
`sessions:read`	Read live sessions and their analytics (numbers).	None
`sessions:write`	Start, steer, speak into and end sessions.	None
`transcripts:read`	Read conversation words (transcripts, summaries) where the privacy rules allow.	Keys made before 2026-10-01 hold it through `sessions:read`.
`results:read`	Read released results, reports (numbers), certificates and completion records.	None
`results:write`	Review, void and grant results; revoke certificates (a named person decides).	None
`assignments:read`	Read assigned work.	None
`assignments:write`	Assign work.	None
`candidates:read`	Read roles, invites and candidates.	Keys made before 2026-10-01 get it only by name.
`candidates:write`	Invite candidates and record decisions (a named person decides).	Keys made before 2026-10-01 get it only by name.
`candidates:data`	A candidate's data copy and erasure.	Never part of full access: add it by name.
`candidates:interviews`	Read candidates' interviews: answers, transcript, the written summary and the marks.	Never part of full access: add it by name. Only an owner or admin can put it on a key, in the console: never a key, never a connected app. Every read is logged.
`cases:write`	Send customers case links (a conversation that already knows their case), list them and revoke them.	Never part of full access: add it by name. Only an owner or admin can put it on a key, in the console: never a key, never a connected app. Every read is logged.
`inbox:read`	Read leads, bookings and hand-offs (with contact details) and knowledge gaps.	Keys made before 2026-10-01 get it only by name.
`inbox:write`	Change the status of leads, bookings and hand-offs.	Keys made before 2026-10-01 get it only by name.
`people:read`	Read units, members, learners and guardian links.	Keys made before 2026-10-01 get it only by name.
`people:write`	Add and change units, learners, leaders and observers; record guardian consent. Admin-level places need a full-access key.	Keys made before 2026-10-01 get it only by name.
`consents:read`	Read face and voice consent records.	Never part of full access: add it by name. Only an owner can put it on a key.
`consents:write`	Withdraw face and voice consent.	Never part of full access: add it by name. Only an owner can put it on a key.
`settings:read`	Read switches.	None
`settings:write`	Change switches.	None
`events:read`	Read the event log.	Keys made before 2026-10-01 hold it through `webhooks:manage`.
`webhooks:manage`	Manage webhooks and read their deliveries.	None
`usage:read`	Read minutes and usage.	None

Full access#

A key whose scopes are ["*"] (or empty) has full access: every scope except the sensitive ones you add by name, ["*", "candidates:data"] for example. Only a full-access key can manage keys.

Interview content#

candidates:interviews reads candidates' interviews for your hiring system (see Interviews in your hiring system). Only an owner or admin gives it, in the console: tick Interview content (hiring) when making the key. A key can never give it to another key (403), full access never includes it, and an app or assistant connected to Zentiq never holds it. Every read is logged on the candidate.

Case links#

cases:write sends customers case links from your CRM or helpdesk, lists them and revokes them (see Case links from your CRM or helpdesk). Only an owner or admin gives it, in the console: choose scopes and tick it when making the key. A key can never give it to another key (403), full access never includes it, and an app or assistant connected to Zentiq never holds it: a case link lets whoever holds it talk to your avatar as that customer.

Keys made before 2026-10-01#

A key made before the 2026-10-01 contract keeps exactly what it could do then:

where a scope was split out (transcripts:read from sessions:read, embed:write and portals:publish from portals:write, and the others in the Notes column above), the key holds it through the scope it already had;
a full-access key does not reach candidates:*, people:*, inbox:* or consents:* until an owner adds them to it by name: data it could never reach doesn't become reachable by itself.

GET /v1/me shows what any key may do, after all of this: apiKey.effectiveScopes, apiKey.fullAccess and apiKey.apiVersion (its contract).

Keep keys safe#

On your server only. Never put a key in a web page, a mobile app or a repository. Browsers join live sessions with a session token and embedded portals with an embed token; your server makes both.
One key per integration, with only the scopes it needs, so you can revoke one without stopping the others.
To replace a key (it may have leaked, or someone left): make a new one, switch your server to it, then revoke the old one in the console or with DELETE /v1/keys/{id}. Revoking works at once.
Watch it: GET /v1/keys lists every key with when it was last used, never its secret.