Personas and Secrets

Personas and secrets

Most useful web tasks are behind a login. Writ stores those credentials for you so a workflow can sign in without them being typed into a step.

Secrets

Secrets holds two shapes:

Login credential	A username and password pair.
API key / token	A single opaque value.

Reference one from any step with {{vault:name}}. The value is substituted at run time on the agent and never rendered back into the UI or written into a run record.

Personas

A persona is a whole browsing identity for one site:

• Login credentials, Fernet-encrypted at rest
• A warm session — cookies and localStorage — reused by every workflow that uses the persona, so most runs skip the login entirely
• Second factor, when the site demands one

Reusing the session matters for more than speed: repeatedly logging in from a new session is exactly the pattern that trips a site's fraud heuristics.

Two-factor

Supported methods: totp, email_otp, sms, or none.

For TOTP, store the base32 seed with the persona and codes are generated at run time. The seed is encrypted with SECRET_ENCRYPTION_KEY like everything else in the vault.

For email OTP, attach a mailbox (IMAP) to the persona and the agent reads the code from the message when a login asks for one.

Encryption at rest

Credentials, TOTP seeds and session cookies are stored in Fernet-encrypted columns keyed by SECRET_ENCRYPTION_KEY.

Back that key up separately from the data volume. A database backup without it cannot be decrypted. Replacing it is as destructive as losing it — every stored persona and secret becomes unreadable, and nothing errors at boot to tell you. See Backup and restore.

What the UI will not show you

Once stored, a secret value is never returned to the browser. The API surfaces metadata — name, kind, when it was last used — and nothing else. If you lose a value, replace it; there is no reveal.

Good practice

• One persona per site per identity, not one shared across sites.
• Give each API key the narrowest scopes that work.
• Rotate anything that has been in a shell history, a CI log or a screenshot.