Secret Management

Preview Feature

Secret management is currently a preview feature. You are seeing an early version of this functionality, which may change in future updates as we continue to improve the experience.

Codesphere provides a Secret Management system integrated with OpenBao, an open-source security vault. This ensures that sensitive data, such as API keys, database credentials, and certificates, are stored with industry-standard encryption and injected into your services only when needed.

Overview

Unlike standard environment variables, secrets are stored in a vault shipped with a Codesphere instance. This provides several advantages:

• Encryption at Rest: All values are encrypted before being persisted.
• Granular Access: Only services explicitly referencing a secret can access its value.
• Automatic Cleanup: Secrets are bound to the lifecycle of the workspace.

info

Currently only admins of a Codesphere installation have direct access to the vault.

Referencing Secrets

Secrets are managed within the Landscape Config Editor. To define a secret, you must use a specific templating syntax regardless of whether you are using the UI or the YAML configuration.

Template Syntax: ${{ vault.secretKeyOfBao }}

UI Configuration

To add a secret to a service using the visual editor:

1. Open the Landscape Config Editor in your workspace.
2. Select the service you wish to configure and open the Edit Service fly-in sheet.
3. Navigate to the Values tab.
4. Add a new entry using the templating syntax:
   • Key: The Environment Variable name the service will use (e.g., SECRET_KEY).
   • Value: The template referencing the vault key (${{ vault.secretFoo }}).

Configuring environment variables using vault templates in the service values tab.

YAML Configuration

For direct configuration, secrets are defined in the env section of your ci.yml profile. Codesphere parses these templates during the sync process and injects the corresponding OpenBao entries into the service environment.

schemaVersion: v0.2
prepare:
  steps: []
test:
  steps: []
run:
  secret-demo:
    steps:
      - command: echo $SECRET_KEY
    plan: 8
    replicas: 1
    network:
      ports:
        - port: 3000
          isPublic: false
      paths: []
    env:
      SECRET_KEY: ${{ vault.secretFoo }}
      PLAIN_ENV: foo

Advanced Environment Templates

Beyond vault secrets, Codesphere supports dynamic templates to reference system-level IDs or existing workspace environment variables. These are particularly useful for making your configuration portable or remapping variables.

Template	Description
${{ workspace.id }}	Resolves to the ID of the Workspace containing the landscape.
${{ workspace.devDomain }}	Resolves to the Dev Domain of the Workspace containing the landscape.
${{ team.id }}	Resolves to the ID of the team owning the workspace.
${{ workspace.env['KEY'] }}	Resolves to a global workspace environment variable.

Use Case: Variable Remapping

The ${{ workspace.env[...] }} template allows you to map global variables to specific service requirements.

For example, if a backend service expects an environment variable named PG_USER, but your database credentials are saved globally as BACKEND_PG_USER to avoid naming collisions with other databases, you can map them like this:

env:
  PG_USER: ${{ workspace.env['BACKEND_PG_USER'] }}

Syncing and Persistence

After defining the secret references, you must sync the Landscape Profile within the Execution Manager.

The Sync Process

When the selected ci.yml contains new secret references during a landscape synchronization, the user is responsible for providing the actual secret values. The process follows these steps:

1. User Prompt: A modal appears prompting you to provide the secret entries defined in your configuration.
2. Input: You must enter the secret key and its corresponding real value at least once to initialize the entry in the vault.
3. Persistence: Once submitted, these values are persisted in the OpenBao instance.
4. Injection: The sync proceeds, and the landscape accesses the vault keys to inject them into the respective services.

The secret input modal triggered during the landscape sync process.

info

Ahead of any landscape synchronization, you can manually override existing secrets as well.

warning

Landscape synchronizations will fail if a service defined in the CI profile cannot access the secret entry it references. Ensure that all secrets are set up correctly during the first deployment of a Landscape.

Managing Secrets via the Public API

The Codesphere Public API exposes a full set of vault endpoints, allowing you to manage and auto-generate workspace secrets programmatically — for example, in a CI/CD pipeline or an internal developer platform. Authentication and general API usage are covered in the Public API documentation.

All vault endpoints follow this base path:

/vault/teams/{teamId}/workspaces/{workspaceId}

Store secrets

POST /vault/teams/{teamId}/workspaces/{workspaceId}

Writes one or more secret key-value pairs to the vault for a given workspace. Returns a map of each key to its revision identifier, which combines a version number and a timestamp.

Request body:

{
  "DATABASE_PASSWORD": "supersecretpassword",
  "API_KEY": "123456789"
}

Response:

{
  "DATABASE_PASSWORD": "1__2026-03-05T10:14:48.490756937Z",
  "API_KEY": "1__2026-03-05T10:14:48.490756937Z"
}

List secret keys

GET /vault/teams/{teamId}/workspaces/{workspaceId}/keys

Returns the list of secret keys stored for a workspace. Values are never exposed through this endpoint.

Response:

["DATABASE_PASSWORD", "API_KEY"]

Delete secrets

DELETE /vault/teams/{teamId}/workspaces/{workspaceId}

Permanently removes the specified secrets from the vault.

Request body:

["DATABASE_PASSWORD", "API_KEY"]

Auto-generate secrets

POST /vault/teams/{teamId}/workspaces/{workspaceId}/generate

Generates cryptographically random secret values and stores them directly in the vault — no plaintext value ever needs to leave your pipeline. The shape of each generated value is controlled by a password policy.

Password policy fields:

Field	Type	Description
length	number	Total length of the generated secret.
rules	array	One or more charset rules applied during generation.
rules[].charset	string	The set of characters to draw from.
rules[].minChars	number	Minimum number of characters from this charset.

Request body:

{
  "DATABASE_PASSWORD": {
    "length": 16,
    "rules": [
      {
        "charset": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
        "minChars": 16
      }
    ]
  },
  "API_KEY": {
    "length": 32,
    "rules": [
      {
        "charset": "0123456789abcdef",
        "minChars": 32
      }
    ]
  }
}

Response — the generated values and their revision identifiers:

{
  "DATABASE_PASSWORD": {
    "value": "aB3kR7mX...",
    "revision": "1__2026-03-05T10:14:48.490756937Z"
  },
  "API_KEY": {
    "value": "1a2b3c4d...",
    "revision": "1__2026-03-05T10:14:48.490756937Z"
  }
}

Use case: zero-knowledge bootstrapping

The generate endpoint is ideal for initial workspace provisioning — you can create strong, unique secrets for every new environment without ever handling the raw values yourself. Reference the vault keys in your ci.yml using ${{ vault.secretKey }} and the secrets are injected at deploy time.

Security and Access Control

Codesphere enforces strict isolation for secret access:

• Reference-Based Access: A service can only retrieve a secret if it is explicitly defined in its configuration.
• Landscape Isolation: Secrets are managed at the landscape level, ensuring that different deployment environments remain separated.

Lifecycle and Cleanup

To maintain a clean security posture, Codesphere automatically manages the lifecycle of your secrets. When a Workspace is deleted:

• All associated secret entries in the vault related to that workspace and its services are identified.
• The system performs a permanent cleanup of all related keys.
• No sensitive data remains available after the workspace is removed.