Projects

Secrets

Project Secrets are key-value pairs that are passed to the Spice Runtime instance as environment secrets. Secrets are securely encrypted and accessible only through the project in which they were created. To share one secret across several projects, use an org secret instead.

Once a secret is saved, its value cannot be retrieved through Spice Cloud. Editing a secret replaces its value; the name cannot be changed.

The Secrets section is available to org owners, admins, and members. Viewers cannot view or manage secrets.

Create a new secret

  1. Select your project.
  2. Navigate to Settings tab and select Secrets section.
  3. Fill Secret Name and Secret Value fields and click Add.
  4. Saved secrets can be referenced in the Spicepod configuration as
    ${secrets:<SECRET_NAME>}, for example:
models:   
  - from: openai:gpt-5.6
    name: gpt-5.6
    params:
      openai_api_key: ${secrets:OPENAI_API_KEY}
  1. To apply secrets, you must initiate a new spicepod deployment. Learn more about deployments.

Secret names must start with a letter or an underscore and may contain only letters, numbers, and underscores.

Move plain-text secrets out of spicepod.yaml

Spice Cloud refuses a save that adds a plain-text password, token, API key, private key, or URL password to spicepod.yaml. Org members can read a saved spicepod.yaml, and anyone can read the spicepod.yaml of a public project. Store each value as a secret and reference it instead.

When spicepod.yaml has a plain-text secret, the Code tab marks the value and shows Move to secrets:

  1. Select Move to secrets. A save that adds a plain-text secret opens the same dialog.
  2. Select Project secret or Org secret.
  3. Check the name of each secret. Spice Cloud suggests a name that no other secret uses.
  4. Select Move and save.

Spice Cloud encrypts and stores each value, links an org secret to the project, puts a ${secrets:NAME} reference in place of the value, and saves spicepod.yaml.

The management API refuses the same change with status 400 and code plaintext_secrets. The response lists the path of each value. It never includes the value.

A spicepod.yaml saved before this check can keep its plain-text secrets, but a save cannot add another one. After you move a secret, rotate the credential at its provider, because earlier versions of the spicepod still hold it. For a project connected to a GitHub repository, replace each value with a reference in the repository.

Linked Organization Secrets

Secrets defined for the org are listed under Linked Organization Secrets. Only the secrets selected and saved here are available to the project at runtime and in secret pickers. When a project secret and a linked org secret have the same name, the project secret takes precedence.

Learn more about org secrets.