Voiceflow bearer token
Secrets
Manage credentials used by your agent’s tools.
See Authentication for credentials and permissions.
Legacy - 2026/08
Returns the secrets defined on a project: name, visibility and whether a value has been stored for it, never the value itself. To learn which environment versions hold a value, use the override list. The call is unpaginated: it takes no paging parameters, so one request yields the whole set.
Authentication
Query parameters
The ID of the project to operate on.
Response
Returns every secret on the project with its ID, name, visibility, whether a value has been stored, and its timestamps; values are never included.
Legacy - 2026/08
Creates a secret on the project, optionally with its value, which is written to the main environment's published version and never read back. Omit the value to create a placeholder for a teammate to fill in the Voiceflow UI; MCP clients must create it empty.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
Request body
The name of the secret. Must be unique within the project.
The secret's value, written to the main environment's published version, the one serving live traffic. It cannot be empty. Omit it to create the secret as a placeholder with no value — a teammate can fill it in later through the Voiceflow UI or CLI.
Whether the value can be revealed in the Voiceflow UI. restricted secrets can never be read back by anyone.
Response
Returns the new secret with its generated ID, the value to reference from a tool input default so the credential is injected at runtime, plus its name, visibility and whether a value is stored. When a value was sent, the response also names the environment version it was written to.
Present when a defaultValue was sent: the alias of the environment that now serves the value (main). Omitted when no value was sent, or when the project has no main environment to name, such as a project that predates environments.
Present along with environmentAlias: the version of that environment that now serves the value, always published, the version serving live traffic.
Current - 2026/09
Returns every secret on the project in one response, with its name, visibility and whether a value is stored, never the value. A tool field binds a secret by name in a {secret_name} token.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
Response
Returns every secret on the project with its ID, name, visibility, whether a value has been stored, and its timestamps; values are never included.
Current - 2026/09
Creates a project secret, optionally with a value written to the main environment's published version and never read back. Names take letters, digits and underscores, because a {secret_name} token binds by name. Omit the value to leave a placeholder; MCP clients must.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
Request body
The name of the secret. Letters, digits and underscores only, at most 64 characters — this is what a {token} in a default-value field binds to. Must be unique within the project.
The secret's value, written to the main environment's published version, the one serving live traffic. It cannot be empty. Omit it to create the secret as a placeholder with no value — a teammate can fill it in later through the Voiceflow UI or CLI.
Whether the value can be revealed in the Voiceflow UI. restricted secrets can never be read back by anyone.
Response
Returns the new secret with its generated ID, name, visibility and whether a value is stored. When a value was sent, the response also names the environment version it was written to.
Present when a defaultValue was sent: the alias of the environment that now serves the value (main). Omitted when no value was sent, or when the project has no main environment to name, such as a project that predates environments.
Present along with environmentAlias: the version of that environment that now serves the value, always published, the version serving live traffic.
Returns which environment versions hold a value of their own for each secret, as secret IDs grouped by environment alias and draft or published variant; values are never included. The call is unpaginated: it takes no paging parameters, so one request yields the whole set.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
Response
Returns one entry per environment version that holds a value for at least one secret, each with the environment alias, the draft or published variant, and the IDs of the secrets with a value there.
Deletes a secret by ID, taking every value stored for it, on every version of every environment, with it. The response carries only a confirmation message, so refetch the secret list to see what is left.
Authentication
Voiceflow bearer token
Path parameters
The ID of the secret to operate on.
Query parameters
The ID of the project to operate on.
Response
Confirms the secret was deleted. The body is a message only, so refetch the secret list and the override list to see it gone from both.
A human-readable message confirming the deletion.
Current - 2026/08
Sets a secret's value on one environment version. Without environmentAlias it writes main's published version, or its draft when versionVariant is draft; with it, versionVariant names the version. The value is never read back; MCP clients cannot call this.
Authentication
Voiceflow bearer token
Path parameters
The ID of the secret to operate on.
Query parameters
The ID of the project to operate on.
Request body
The secret value to store. Write-only — it can never be read back through this API.
The alias of the environment to write (e.g. staging). Without it the value goes to the main environment. Requires versionVariant.
Which version of the environment to write: published, the version serving live traffic, or draft, the one used when testing. Required with environmentAlias. Without environmentAlias it defaults to published, and draft writes the main environment's draft version; a project with no main environment has no draft version, so the request is then handled as if versionVariant were omitted.
Response
Confirms the value was stored and names the environment version it was written to. Only when there is no environment to name, such as a project that predates environments, does the confirmation stand alone.
A human-readable message confirming the update.
The alias of the environment that now serves the value (e.g. main). Omitted only when there is no environment to name: the project predates environments, or no environmentAlias was given and the project has no main environment.
Which version of that environment now serves the value: published, the version serving live traffic, or draft, the one used when testing.
Legacy - 2024/11
Sets or removes an environment-specific override for a secret. Pass null as the value to delete the override. Use versionVariant to target the draft or published version of the environment.
Authentication
Voiceflow API key
Path parameters
The ID or alias of the environment to target (ie. main). You can find this in the environments page of your agent.
> 💡 Tip: Learn more about Environments.