Working with secrets.
Secret handles
You never see secrets through Zeqqat. When a result contains one (a database password, an API token, an env var such as DATABASE_URL), it arrives as a handle like {{zq_secret_ab12cd34ef56gh78}} instead of the value. To use the secret, put the handle in a later zeqqat_run input, alone or inside a string, and Zeqqat fills in the real value just before the request goes out. For example, to copy a database URL into an app: env set to DATABASE_URL=postgresql://app:{{zq_secret_...}}@db:5432/app. Never ask the user to paste a secret into the chat; use a handle. Handles expire after 30 minutes; read the value again for a fresh one.
Creating new secrets
When a task needs a new password or key (a database password, a session secret, an encryption key), call zeqqat_secret. It returns a handle for a fresh random value. kind password gives letters and digits (length in characters, default 32); kind base64 or hex gives random bytes (base64 with length 32 is a typical signing key). Use the same handle everywhere the same value is needed, for example as databasePassword in postgres.create and inside DATABASE_URL in the app's env. The value is stored only where you write it; Zeqqat deletes its copy when the handle expires.
Where handles work
A handle only resolves in fields meant for secrets: an env block (env, previewEnv, buildArgs, buildSecrets) or a field whose name says it holds a secret (password, token, key, secret). Anywhere else, such as a webhook URL, a notification target or a description, the call is refused. A handle works only on the connection it came from, and on one instance: the one its value came from, or for a zeqqat_secret handle, the first instance it is used on. An unknown or expired handle is refused with nothing sent.
Next: Errors