Skip to main content


This guide explains how to use secrets to keep private keys secure while using Gradient.


Secrets provide a mechanism to securily store and work with sensitive information (such as an API key) within Paperspace. Secrets can be safely injected into workloads as environment variables. An environment variable that uses a Secret will not reveal the contents of the secret itself.

An example Secrets use case

When using other services that require authentication via an API key, this key can be stored as a Secret within Paperspace and then passed-into the workload that requires the API key. This would prevent the key itself from being visible to other team members. It would also guard against accidentally exposing the API key such as checking-in it into source control.

Managing and Using Secrets

Secrets can be created at the following levels:

  • Team: these secrets are applied to all projects and all clusters
  • Gradient Project: these secrets are applied to all Workflows in a project
  • Gradient Cluster: these secrets are applied to all Workflows in a cluster

Secrets can be set from the Settings tab in the console or through the CLI.

Set a Secret

gradient secrets set cluster --id=<cluster_id> --name=<name> --value=<secret>
Navigate to one of:
  • The Secrets tab under Team settings
  • The Settings tab under a Project
  • The Secrets tab in the details of a Cluster under the Team settings Clusters tab
These correspond to Team, Project, and Cluster secrets respectively. Type in the name and value of the secret, and click Add to save.

List Secrets

Navigate to the Project, Team, or Cluster page, as with setting a secret above. The names of secrets in that scope that are already stored are listed.

Delete a Secret

Navigate to the Project, Team, or Cluster page, as with setting a secret above. Click the Delete button and confirm the dialog.

Secret scoping

If the same secret name is created for more than one scope, only one will be applied. Secrets with the same name have the following precedence:

  • Cluster secrets take precedence over Team secrets
  • Project secrets take precedence over both Cluster secrets and Team secrets.

How to store an API key as a Secret

Certain actions within Gradient require incorporating your API key to authenticate requests. In cases where your API key is used within your code or commands that may be visible within your Gradient team (e.g., a Notebook) or other locations (e.g., when checking your code into source control), you will want to use Secrets to mask your unique API key.

1. Create a new API key

Go to the API Keys tab under team settings, type a name for the key, and click Add.

Once your key is created, copy the key to your clipboard.

2. Save the key as a Secret

API keys can be added in a similar way to other secrets: type a name, paste the API key in the Value field, and click Add.