Environments and keys
One environment per kind, its publishable and secret keys, allowed origins, retention, and the one time a secret key can ever be read.
A workspace holds apps. An app holds environments. An environment is where a guide actually runs, and it is the unit everything else hangs off.
One of each kind
| Kind | Created by | Allowed origins at creation |
|---|---|---|
development | Setup, when you create the app | http://localhost:5173 and http://localhost:4173 |
staging | Settings, Environments, Add environment | none |
production | Settings, Environments, Add environment | none |
An app has at most three environments, one of each kind. Asking for a second of a kind is refused.
Staging and production start with no allowed origins on purpose. A production key that accepted localhost would be usable from any laptop, so you add the real origin before the first session can mint.
What an environment holds
| Setting | Where | Notes |
|---|---|---|
| Publishable key | shown at creation, and Settings, Keys | dk_pub_.... Ships in the browser. |
| Secret key | shown at creation, and Settings, Keys | dk_sec_.... Server and CI only. |
| Signing secret | Settings, Keys | Signs userTokens. Readable only by rotating it. |
| Allowed origins | Settings, Environments | The only fence the publishable key has. An empty list stops the guide everywhere. |
| Retention | Settings, Environments | Whole days, 0 to 90. Zero keeps nothing once the session ends. Defaults to 30. |
| Presence | Presence | Which character this environment's users see. |
| Voice | Voice | What it sounds like, per vendor. |
| Route list | uploaded by docent sync | Per environment. |
Knowledge packs are the exception: they belong to the app, so every environment of an app answers from the same knowledge.
The three credentials
Publishable key, dk_pub_.... Safe in browser code. It does one thing, open a session, and
it does it only from an origin on the list. The session mint refuses a request with no Origin
header, an origin that is not allowed, or a key it does not recognise, and it rate limits per key
and origin.
Secret key, dk_sec_.... Never in a browser. It is what docent sync and docent crawl
authenticate with.
Signing secret. A separate value, and the one your server signs userTokens with. It is not
a dk_ key and it does not upload anything.
# server, or CI
DOCENT_SECRET_KEY=dk_sec_...
# browser
NEXT_PUBLIC_DOCENT_PUBLISHABLE_KEY=dk_pub_...Minting, rotating and revoking
Settings, Keys lists every key by its twelve-character prefix, when it was created and when it was last used. A key's plaintext exists in exactly one HTTP response and is never stored, so it is shown once in a drawer and the row behind it carries only the prefix. Copy it then.
An environment can hold more than one key of a kind, which is how a rotation happens without an outage: create the new one, deploy it, then revoke the old one. Revoking takes effect immediately.
Rotating the signing secret is the one destructive control here, and the Console asks you to type
the environment's name to confirm it. It invalidates every userToken you have already signed,
so deploy the new secret before your users notice.
Allowed origins
An origin is a scheme and a host with no path, such as https://acme.com. Anything that does not
parse as one is refused rather than corrected. Matching is exact and case-insensitive. There are
no wildcards.
https://acme.com
https://app.acme.com
http://localhost:3000Every subdomain your app is served from needs its own entry. A preview deployment on a generated hostname needs that hostname, which is usually the reason to point previews at the development or staging environment rather than production.
Verified sessions
userToken is optional and is how a host proves the user id it passed is real. Your server signs
an HS256 JWT with the environment's signing secret, carrying sub set to the same user id you
pass in user.id and aud set to docent. The gateway verifies both claims and marks the
session verified. A token that does not verify is refused and the session does not start, so send no
token rather than a stale one.
Without it the guide still works. Verified is what cross-session memory and handoff attachments require.
Retention
Each environment keeps the masked text of turns, tool calls, latencies, routes and a small set of named events for its retention period, between 0 and 90 days. The cap is the product rule, and it is enforced at the API as well as in the Console. See Privacy for what is kept and what is never kept.
CLI
The Docent CLI. sync uploads routes and Markdown knowledge, crawl reads a docs site, with every flag, every limit and what each command prints.
Presence and voice
The fifteen presences an owner can choose, how the SDK loads one, the ten live voices, and when the guide is allowed to open a microphone.