Skip to main content
The Kubiya Secrets service provides a secure interface for managing sensitive data and credentials used by workflows and tools. It supports creating, listing, updating, and deleting secrets, as well as secure retrieval of secret values when required by workflows or tools.

​
Features

  • Secure secret storage and retrieval
  • Create secrets from direct values or from files
  • Metadata-only listing vs. value retrieval
  • Validation and error handling for secret operations

​
Quick Start

from kubiya import KubiyaClient

# Initialize client
client = KubiyaClient(api_key="your-api-key", base_url="https://api.kubiya.ai")

# Access secrets service
secrets = client.secrets

​
Common operations

Create a secret (value or file): 
client.secrets.create(name="database-password", value="super-secure-password-123", description="DB password")
List secrets (metadata only): 
client.secrets.list()
Get secret metadata: 
client.secrets.get("database-password")
Retrieve secret value (use carefully): 
value = client.secrets.value("database-password")
# Do not log the secret value
Update and delete are available via client.secrets.update(...) and client.secrets.delete(...).

​
File-based secrets

You can create a secret from a file when the secret is large or managed outside code: 
client.secrets.create(name="api-key-from-file", from_file="/path/to/file")

​
Integration with Workflows and MCP

  • Secrets are exposed to workflows via environment mappings or parameters marked as secret.
  • The MCP compile_workflow tool analyzes workflows for secret placeholders and will either add parameter placeholders for missing secrets or accept provided secret values (see MCP Server docs).

​
Error Handling

  • SecretValidationError indicates invalid input (empty name, missing value, conflicting args).
  • SecretError indicates operational issues (file not found, permissions, not found on retrieval).

​
Best Practices

  • Never print secret values or include them in logs.
  • Use descriptive but non-revealing secret names and include environment prefixes.
  • Rotate secrets regularly and use client.secrets.update() to rotate.
  • When creating secrets from files, ensure secure file permissions and remove temporary files after use.

​
Code Examples and Patterns

Safe retrieval helper: 
def get_secret_safely(client, name: str) -> str:
    try:
        return client.secrets.value(name)
    except Exception as e:
        # Handle SecretError/SecretValidationError appropriately
        raise

​
Where to use

  • Use the Secrets service when workflows need credentials for cloud providers, APIs, or databases.
  • Prefer passing secret references (parameters/env mappings) to workflows rather than embedding values in DSL source.