Create, store, and manage environment variables and secrets

Environment secrets are securely encrypted values that function as environment variables within your workflows.

They enable you to store and manage sensitive configuration data, such as third-party API keys, without hardcoding them into your scripts.

Via the UI

The Clarifai platform offers an intuitive interface for creating, managing, and securing your environment secrets.

To create a secret, log in to the Clarifai platform. Then, in the collapsible left sidebar, select Settings and choose Secrets from the dropdown list.

On the ensuing Secrets page, click the Create Environment Secrets button.

Next, on the form that pops up, enter a required name for your secret, an optional short description, and the required value.

Lastly, click the Create Environment Secret button.

The new secret will be listed in the Environment Secrets section, where you can copy, view, edit, or delete it.

Note:

• Environment secrets do not expire. In case your secret gets compromised, you should delete it, and create a new one.
• We recommend that you do not share your secrets with other users.

Via the API

Prerequisites

Install Python SDK

Install the latest version of the Clarifai Python SDK package.

 pip install --upgrade clarifai

Get Credentials

Go to your Clarifai account and retrieve the following credentials:

• User ID – In the collapsible left sidebar, select Settings and choose Account from the dropdown list. Then, locate your user ID.
• PAT – From the same Settings option, choose Secrets to generate or copy your Personal Access Token (PAT). This token is used to authenticate your connection with the Clarifai platform.

You can then set the PAT as an environment variable using CLARIFAI_PAT.

• Unix-Like Systems

 export CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE

• Windows

 set CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE

Create

You can create a new environment secret by providing its ID and value.

• Python SDK

from clarifai.client.user import User

# Set PAT as an environment variable before running this snippet:
#   export CLARIFAI_PAT=YOUR_PAT_HERE # Unix-Like Systems
#   set CLARIFAI_PAT=YOUR_PAT_HERE  # Windows

# # Initialize User client
client = User(user_id="YOUR_USER_ID")

# Create one or more secrets
secrets = [
    {
        "id": "OPENAI_KEY_2025",
        "value": "your_super_secret_api_key_here",
        "description": "My OpenAI key for experiments"
    }
]

created_secrets = client.create_secrets(secrets)
print("Created Secrets:", created_secrets)

• cURL

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/secrets" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": [
      {
        "id": "OPENAI_KEY_2025",
        "value": "your_super_secret_api_key_here",
        "description": "My OpenAI key for experiments"
      }
    ]
  }'

Get

You can get an existing environment secret by providing its ID.

• Python SDK

from clarifai.client.user import User

# Initialize User client
client = User(user_id="YOUR_USER_ID")

# Retrieve a specific secret by its ID
secret_info = client.get_secret(secret_id="OPENAI_KEY_2025")
print("Secret Info:", secret_info)

• cURL

curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/secrets/YOUR_SECRET_ID_HERE" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json"

List

You can list all the environment secrets you have.

• Python SDK

from clarifai.client.user import User

# Initialize User client
client = User(user_id="YOUR_USER_ID")

# List all secrets
all_secrets = list(client.list_secrets(page_no=1))

print("Secrets:")
for secret in all_secrets:
    print(secret)

• cURL

curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/secrets" \
  -H "Authorization: Key YOUR_PAT_HERE"

Note: If you specify page_no but not per_page, pagination defaults to 16 items per page. If both page_no and per_page are left as None, all resources are listed without pagination.

Update

You can update an existing environment secret by providing its ID.

• Python SDK

from clarifai.client.user import User

# Initialize the client
client = User(user_id="YOUR_USER_ID")

# Update an existing secret's description or value
patched_secrets = client.patch_secrets(
    secrets=[
        {
            "id": "OPENAI_KEY_2025",
            "value": "new_secret_value",
            "description": "Updated Secret Description"
        }
    ],
    action="overwrite"  # Can also be "remove"
)

print("Patched Secrets:", patched_secrets)

Delete

You can delete an existing environment secret by providing its ID.

• Python SDK

from clarifai.client.user import User

client = User(user_id="YOUR_USER_ID")

# Delete one or more secrets
client.delete_secrets(secret_ids=["OPENAI_KEY_2025"])

Use Case Examples

Custom Models

The config.yaml file defines the build, deployment, and runtime configuration for a custom model on the Clarifai platform. You can also use this file to reference sensitive configuration values without hardcoding them into your application code.

Pipelines

Clarifai Pipelines allow you to design and run asynchronous, multi-step AI workflows on the platform. The root config.yaml file defines the pipeline’s identity, structure, and orchestration logic. It specifies which steps the pipeline contains and how they are executed.

Your application can then read the secret using a standard environment variable.

import os

github_token = os.environ["GITHUB_PERSONAL_ACCESS_TOKEN"]

At runtime, the platform securely injects the secret value into the environment, allowing your code to use it without exposing sensitive information in your project files.