Secret and connector tools

Overview

These tools manage the secrets in your organization's vault and check the credentials stored in your connectors.

To list secret names or connectors, use search_orchestrator_resources. To see what uses a connector, use cross_reference.

The three secret tools are write tools, see Availability.

Secrets

A secret is a single encrypted value stored under a name in your organization's vault. Workflows, git sources and policies refer to it by name, so its value never has to appear in their configuration.

Secret values are never returned. No tool, and no API, reads a secret's value back. Values are never echoed in responses, not even in error messages. A wrong value can only be fixed by rotating it.

caution

When you give your AI assistant a secret value, the value is part of your conversation with it. If a value shouldn't pass through your AI assistant, create or rotate the secret in the dashboard instead.

Referring to a secret

When a secret is created, the response gives two ways to refer to it:

Form	Use it in
/secrets/<name>	Environment variables that take a secret, and git or policy authentication.
${secret::<name>}	Inside plain-text values, such as environment variables, IaC inputs and webhook secrets.

Permissions

Action	Roles
Create a secret	Admin, Developer, Security or Ops
Rotate or delete a secret	Admin or Ops

create_secret

Stores a new secret in your organization's vault.

Input	Description
Name (required)	1–71 characters: letters, digits, _ and -. Names are case-sensitive and permanent; a secret can't be renamed. Some platform-reserved words can't be used.
Value (required)	Up to 7,096 characters and 8 KB. Stored exactly as given, including whitespace and newlines. For example, an SSH private key keeps its trailing newline.

Good to know

• If the name is taken, the response says so. Use update_secret to change an existing secret's value.
• You get a warning if another secret has the same name in a different case, since that creates a second, separate secret.
• You also get warnings if the value is larger than 4 KB (it's stored in a paid, higher tier), contains $name-style text that could be expanded as a variable when used in Terraform, or contains newlines.
• A new secret can take a few seconds to show up in search results.

Example prompts

"Create a secret called datadog-api-key."

update_secret

Rotates the value of an existing secret. Only the value can change.

The tool checks that the secret exists first. The platform's update would otherwise silently create a new secret from a mistyped name.

Workflows keep referring to the same secret and pick up the new value at their next run. Runs already in progress keep the old value.

The tool doesn't check which workflows use the secret. To see the impact first, ask your assistant to search for workflows that reference it, bearing in mind that this search is partial.

Input	Description
Name (required)	The exact, case-sensitive name of an existing secret.
Value (required)	The new value. Same limits as create_secret.

Example prompts

"Rotate the db-password secret. Which workflows will pick up the new value?"

delete_secret

Permanently deletes a secret. There's no undo, and every workflow still referring to the secret fails at its next run.

The platform doesn't check what uses a secret before deleting it, so the tool does:

1. It confirms the secret exists.
2. It searches for workflows that reference the secret and returns an impact report.
3. It deletes only when you explicitly confirm. Without confirmation it returns the impact report and changes nothing.

Your assistant should show you the referencing workflows and get a clear yes before deleting.

note

The impact search is partial. It finds ${secret::<name>} references in plain-text environment variables only. It doesn't see secret-type environment variables (/secrets/<name>), git, policy or container authentication settings, or IaC inputs. It lists at most 50 workflows and says when the list is only a sample. Review anything it couldn't check before you confirm.

Input	Description
Name (required)	The exact, case-sensitive name of an existing secret.
Confirmation	Required to actually delete.

Example prompts

"What would break if I deleted the old-github-token secret?"

"Delete the old-github-token secret."

Connectors

authenticate_integration

Checks whether a connector's stored credentials still work, for example an AWS role or keys, an Azure or GCP service principal, or a GitHub, GitLab, Bitbucket or Azure DevOps token. You can check:

• one connector
• one connector inside a connector group
• a whole connector group, in which case every connector in it is re-checked in the background. The result reflects the group; check a connector by its own id to see its individual result.

It returns only whether authentication succeeded and when. It never returns credentials.

This isn't a pure read. Each call makes StackGuardian perform a live check against the provider, such as assuming the role or exchanging a token, and updates the connector's stored authentication status. It's safe to repeat, but it isn't meant for polling.

Example prompts

"Is our aws-prod connector still able to authenticate?"

"Re-check every connector in the azure-subscriptions group."