Account secret setup guide

Use the hosted /account/secrets/new page whenever the user needs to enter a secret value such as an API key or personal access token. The agent must never see the secret value.

If the secret will power a downstream playbook or playbook app, open search({ entity: "integration_bootstrap:guide" }) before building that playbook. For the common non-OAuth path after bootstrap, open search({ entity: "secret_backed_integration:guide" }). This guide covers the secret-collection step only.

When to use /account/secrets/new

Use it when:

• the user must provide a sensitive value
• a named secret needed for fetch placeholders or a named lookup (for example secretJwtSign) is missing
• the user needs to rotate a stored secret value

Do not ask the user to paste secrets into chat.

URL format

Provide the user a URL like:

https://<your-kody-origin>/account/secrets/new?name=exampleApiKey&description=Example%20API%20key&expiresAt=2026-12-01T00:00:00.000Z&allowedHosts=api.example.com&scope=user&allowedPlaybooks=pkg_123

When name is present, the page focuses and scrolls to the secret value input so the user can paste immediately.

Query params

Approval policy reminders

• Saving a secret does not approve outbound hosts.
• The account form prefills the requested hosts and playbooks for review.
• Host approval uses the dedicated /connect/secrets page (name / names and hosts). Playbook grants use /account/secrets/approve.

Playbook approval URLs (after a playbook exists)

Self-authored personal playbooks can read and use the user's secrets without an allowed_playbooks grant; updating or deleting a user secret from playbook code still requires that grant. Agents can add a playbook to that grant with secretLock; removing a grant is website-only. When a playbook operation requires an additional grant on an existing secret, send the returned approval link; do not ask the user to recreate the secret. Source edits do not widen grants.

• Single secret: /account/secrets/user/{secretName}?playbook_id={savedPlaybookId}&playbook={kodyId}
• Multiple secrets for one playbook (preferred): /account/secrets/approve?playbook_id={savedPlaybookId}&playbook={kodyId}&names={secret1},{secret2}

Prefer the bulk /account/secrets/approve?...&names=... URL whenever two or more secrets still need playbook approval. The account UI shows every listed secret and lets the user approve them in one click.

Agent instructions

1. Generate the URL with the required name and any optional params.
   • When using scope=playbook, include the saved playbook id in playbookId.
2. Ask the user to open the URL in their browser.
3. Wait until they confirm the secret is saved.
4. If the secret will back a playbook or playbook app, run the authenticated smoke test described in guide: "integration_bootstrap" before saving the downstream playbook.
5. For common non-OAuth integrations, continue with guide: "secret_backed_integration" after the secret exists.
6. Proceed using {{secret:name}} fetch placeholders or a named secret lookup such as secretJwtSign.