Skip to docs content
Browse documentation
On this page

Secret setup

How to get an API key or PAT into Minion: the Secrets page form, its fields, approval reminders, and what an agent should say and wait for.

Use the Secrets page whenever a person needs to enter a secret value such as an API key or personal access token. Secrets stay on that page: send the person there, tell them which name to use, and wait until they confirm it is saved. Never ask for the value in chat.

If the secret will power a downstream package, open search for guide:connect_an_integration or the integration bootstrap guide before building that package. For the common non-OAuth path after bootstrap, see Secret-backed integrations . This guide covers the secret-collection step only.

When to use the Secrets page

Use it when:

  • the person must provide a sensitive value
  • a named secret needed for fetch placeholders or secrets.jwtSign is missing
  • the person needs to rotate a stored secret value

Only owners and admins can add or change secrets. Members see the names but can't save values.

The form

The Add a secret card has these fields. The page has no prefilled links: tell the person what to type in each one.

  • Name. Required. Starts with a letter, then letters, digits and underscores, up to 64 characters (for example exampleApiKey). Code refers to it as {{secret:exampleApiKey}}.
  • Value. Required. Encrypted on save and never shown again.
  • Approved hosts. Comma or space separated hostnames the secret may be sent to, such as api.example.com or *.example.com. Saving writes the list with the secret.
  • Expires (UTC, optional). Minion's cutoff for sending the secret, separate from the provider token's own expiration. Leave it empty and Minion keeps the secret until it is deleted.
  • Description. Optional, shown in the list.

To rotate a value, save the same name again with the new value.

Approval reminders

  • If the hosts field was left empty, or a later call says a host is not approved, the person adds the host to that secret on the same page. Hosts must be hostname-shaped; a pasted URL is reduced to its hostname.
  • Saving a secret never approves a host on its own, and an ad hoc smoke test that worked does not widen the allowlist.
  • A provider-issued webhook signing secret also needs Allow webhook use before a package webhook can verify with it, and a signing key for secrets.jwtSign needs JWT use allowed. Neither can be turned on from code.

Agent instructions

  1. Tell the person the exact secret name, the hosts to approve, and the provider page where they can create the token.
  2. Send them to the Secrets page and wait until they confirm the secret is saved. If you're blocked on them, minion.waiting.list() shows what is pending.
  3. If the secret will back a package, run the authenticated smoke test described in the integration bootstrap guide before saving the downstream package.
  4. For common non-OAuth integrations, continue with Secret-backed integrations after the secret exists.
  5. Proceed using {{secret:name}} fetch placeholders or minion.secrets.jwtSign.