Guide

API keys and scopes

Every key is shown once, when it is created. Store it in your secret manager straight away; if you lose it, rotate it.

Two kinds of key

Key	Where it lives	What it can do
`sk_dezifi_…`	Your servers and CI only.	What its scopes allow. Can mint session tokens and can name the end user (X-End-User-Id, X-Customer-Group-Id) on a call.
`pk_dezifi_…`	A web page (the widget), limited to the sites you list.	Runs one agent for anonymous visitors. It cannot say who the user is: for signed-in users use session tokens instead.

Where keys are created

Agent > Deploy > Connect: Your app, MCP and Terminal share one secret key for that agent; Website creates the public key for the sites you enter.
Settings > API Keys > + Generate New Key: secret keys only, as a Personal key or a Service account key, with Permissions, Requests/Min (default 60), Requests/Day (default 10,000), Expires on, Allowed IP addresses and Only for agent.
As code: the DAK ApiKey resource, scoped to exactly one agent or workflow. Its secret is printed once in the dak deploy output.
Deploy keys for the dak CLI: create a service account under Settings > Service Accounts, then a service account key for it.

Scopes you will use

Scope	For
`agent:execute`	Start sessions, send messages, mint session tokens for an agent the key may use.
`agent:read`	Read the agent and its sessions.
`workflow:execute`	Run a workflow.
`customer-group:read / customer-group:write`	List or create the customers your users belong to (B2B organisations).
`privacy:manage`	Forget or export an end user (GDPR requests). agent:execute is no longer enough, and the key must belong to a workspace Admin or Owner.
`customers:manage`	Set up customers: tiers, rollout, alerts, connections, support access (B2B organisations).
`usage:read / billing:export`	Read usage and cost; export the per-customer invoice lines (B2B organisations).
`hitl:read / hitl:approve / hitl:reject`	Read and decide approvals from your own tools.
`knowledge_base:ingest`	Load documents into a knowledge base.
`eval:run / eval:read`	Run experiments and read results (CI).

Naming the end user

With a secret key, send X-End-User-Id (your user's id) on every call and, if your organisation is set up as B2B, X-Customer-Group-Id (the customer they belong to); the SDKs do it with onBehalfOf / on_behalf_of. A B2B organisation refuses an end-user call that names no customer (CUSTOMER_REQUIRED); a B2C organisation refuses one that names a customer (CUSTOMERS_NOT_USED). See B2B or B2C: how your organisation is set up. X-Workspace-ID is optional with a key, but if you send it, it must be the key's own workspace.