API keys
Your two keys — secret and widget — where they come from, exactly what each can do, and how to hold them safely.
Each app has two keys. The secret key (sk_…) is the only credential this API accepts, and it carries the full authority of the account that owns the app. The widget key (pk_…) is public and can only ask questions through the widget.
Finding your keys
Open the console, choose an app, and find the Secret key card in the right-hand column of the app page. Press Create key and copy it at once: we store only a fingerprint of it, so it can never be shown again. Lost it? Make a new one.
sk_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hLKeys are opaque strings prefixed with dk_live_. Treat the whole string as the secret — there is no separate id and secret pair.
What the secret key can do
The secret key authenticates as the user who owns the app. That is broader than it may look, so it is worth stating plainly. A holder of the secret key can:
- List, create, rename and delete any workspace under the app.
- Upload documents into any of those workspaces, and delete them.
- Read every resource's
file_url, which is a direct link to the stored original document. - Ask questions and read the chat history of any end user in any of those workspaces.
Keeping it safe
Which leads to a short list of rules:
- Call the API from your backend only. Not from a browser, a mobile app, a desktop app, or a build artefact your users can download.
- Read it from an environment variable or a secret manager. Never commit it, and never put it in a client-side bundle where a build step could inline it.
- If your users need to ask questions from a browser, proxy through your own server: your frontend calls your API, your API holds the secret key. That also lets you enforce your own rate limits, which this API does not yet have.
- Send a different
external_user_idper end user, so the transcripts you store stay separated even though they share one secret key.
Rotation and revocationOn the roadmap: Soon
Each key has its own Regenerate and Delete buttons on the app page. Both work at once: the old key stops working the moment you press the button. After a delete, the app has no key of that kind until you press Create key. You can change keys up to 10 times an hour.
The widget uses its own public key, not this one. Before you embed it, read Security.