Secret setup URL reference

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. Secrets stay on the setup page; send the URL and wait until they confirm save.

If the secret will power a downstream package or package app, open search({ entity: "guide:integration_bootstrap" }) before building that package. For the common non-OAuth path after bootstrap, open search({ entity: "guide:secret_backed_integration" }). 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

Send the /account/secrets/new URL and have them paste into Secret value on that page.

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&allowedPackages=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

• A prefilled allowedHosts list is on the form under Where this secret can be sent. Saving writes that list with the secret.
• When the save URL omitted hosts, or a later call says a host is not approved, open /connect/secrets (name / names and hosts). Package grants use /account/secrets/approve.
• hosts must be hostname-shaped. Truncated or path-bearing values are rejected on that page and are not written to allowedHosts.

Package approval URLs (after a package exists)

Self-authored packages and adopted community forks (communityForkAdopt) can read and use the user's secrets without an allowed_packages grant; updating or deleting a user secret from package code still requires that grant. Only the account owner can add a package to that grant on the secret editor or /account/secrets/approve — a focused Allow page like /connect/secrets. secretLock returns that approval URL. Send the link and wait until they confirm. The grant is written on that page. Removing a grant is also website-only. When an unadopted community-forked package needs access to one or more existing user secrets, either adopt it after reviewing the source or send the approval link so they keep the secrets they already saved.

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

Prefer the bulk /account/secrets/approve?...&names=... URL whenever two or more secrets still need package 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=package, include the saved package id in packageId.
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 package or package app, run the authenticated smoke test described in guide: "integration_bootstrap" before saving the downstream package.
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.