Working with Secrets

When creating an instance of a service in Open Source Cloud you can provide the instance with parameters. What type of parameters you provide is specific to the service. If a parameter contains sensitive information such as access keys or passwords you don't want to enter them in clear text, and to avoid this we provide the possibility to enter a reference to a Service Secret instead.

Storing credentials? See Secrets vs Parameter Store to choose the right primitive.

What is a Service Secret?

A Service Secret is specific to each service and cannot be shared among the services. You can create and update a secret but once created there is no way to see that the secret contains. To provide the contents of a secret to an instance parameter you refer to it using double curly brackets. For example a secret named mysecret is referenced as {{secrets.mysecret}}.

Creating a secret

A user with the tenant administration role can create and modify secrets. For this user there is a tab called "Service Secret" on the service page.

To create a new secret click on the button "New Secret".

Enter a name of the secret, for example mysecret and enter the secret value. Click on the eye icon to display what you have entered. Once saved it will not be visible anymore.

Now press button "Create Secret" to close the modal and save the secret.

The secret you created is now available in the list of secrets for this service.

Modify a secret

There is no way to actually see the secret but you can modify and change it. Click on the button Edit in the secrets table.

The same dialog is opened with the difference is that you cannot change the name of the secret. Enter the new value and click on Update Secret to save.

Change a secret from the instance parameters view

If an instance parameter was set using a {{secrets.NAME}} reference, the parameters view now shows a chip with the secret name instead of the raw reference text. You can update the secret value directly from this view without navigating to the Service Secrets tab.

To change a secret value from the instance parameters view:

1. Navigate to the service page and click on the running instance card
2. Click Parameters to open the instance parameters panel
3. Locate the parameter that shows a secret name chip (e.g. mysecret)
4. Click the chip to open the Change Secret Value dialog
5. Enter the new value and click Save

The change updates the underlying Service Secret immediately. Because the secret value is write-only, the current value is never shown — only the secret name is displayed.

This is equivalent to using the Edit button on the Service Secrets tab (see Modify a secret) and provides a convenient shortcut when you are already viewing an instance's parameters.

Workspace Secrets

Workspace Secrets are encrypted key-value pairs that are shared across all services in your workspace. Unlike Service Secrets (which are bound to a single service instance), a Workspace Secret can be referenced in any service's configuration form.

Workspace Secrets are managed under Workspace Settings → Workspace Secrets (navigate to app.osaas.io/dashboard/team-settings/secrets).

Use Workspace Secrets when the same credential — for example an API key used by multiple services — needs to be referenced in more than one service instance. The value is stored encrypted and never readable after creation, just like Service Secrets.

Creating a Workspace Secret

1. Navigate to Workspace Settings → Workspace Secrets
2. Click Add secret
3. Enter a key name in the Key Name field. Key names may only contain letters, numbers, dots, and hyphens; the user. prefix is added automatically (e.g. entering github-token stores the secret as user.github-token)
4. Enter the secret value. Use the eye icon to reveal what you have typed
5. Click Add to save

Once saved, the value is never shown again. You can reference the secret in any service's configuration using {{secrets.user.github-token}} (or whatever name you chose).

Deleting a Workspace Secret

1. Navigate to Workspace Settings → Workspace Secrets
2. Find the secret in the table and click Delete
3. Confirm the deletion in the confirmation dialog

Deleting a Workspace Secret is permanent. Any service instance that references the deleted secret via {{secrets.NAME}} will fail to start until the reference is updated or the secret is recreated.

Refer to a secret

Now when you want to provide the instance parameters you can refer to the secrets you created. Either manually by entering the curly brackets or pressing the key button and get a list of secrets to choose from. The dropdown shows both Service Secrets (specific to the current service) and Workspace Secrets (shared across your workspace), so you can pick either type from the same picker.

Providing instance parameters as secrets may now look like this.

Refer to a secret in CLI

When using the Open Source Cloud CLI you can also refer to a secret when creating an instance. For example if you have stored the admin password for your couchdb instance in a secret called mysecret you would refer to it the following way when creating the CouchDB instance using the CLI.

% npx -y @osaas/cli create apache-couchdb mydb -o AdminPassword="{{secrets.mysecret}}"

Credential Safety Safeguards

OSC includes several layers of protection to prevent credentials from being accidentally stored in plaintext or leaked through conversation history.

Credential Indicator on Form Fields

Form fields that accept sensitive values (such as Git tokens, OSC access tokens, and parameter store API keys) display a K8s Secret badge. This confirms the value you enter will be stored in a Kubernetes Secret rather than as a plain parameter — never written to the OSC database.

Unencrypted Parameter Store Warning

If you have parameter stores whose key names look sensitive (containing words like KEY, SECRET, TOKEN, PASSWORD, or CREDENTIAL) but the store was created without encryption enabled, the OSC dashboard shows a warning banner at the top of the page and a warning chip on the affected row in the parameter stores table. Clicking Review parameter stores takes you directly to the Stores tab where you can identify and recreate them with encryption enabled.

Encrypted secrets can only be enabled at creation time — you cannot add encryption to an existing store. See Parameter Store for instructions on creating a store with encryption enabled.

Credential Detection in AI Chat

The OSC AI chat interface (both the My Apps chat and the AI agent feature) includes multi-layer credential detection to keep secrets out of conversation history.

Client-side check: Before a message is sent, the browser scans it for patterns that look like credentials — GitHub Personal Access Tokens (ghp_, github_pat_, gho_, ghu_, ghs_ prefixes), OpenAI and Anthropic API keys (sk- prefixes), JWTs, database connection strings with embedded passwords, and high-entropy strings. If a match is found you are warned and can edit the message before it leaves your browser.

Server-side scanner: Even if a credential-shaped value reaches the server, it is redacted before being stored in conversation history or forwarded to the LLM. The system logs an audit entry recording that redaction occurred (type of credential detected, tenant ID) without storing the value itself.

MCP tool argument scanner: When OSC MCP tools are called through the AI chat, tool arguments are scanned for credential-shaped content. If a secret is detected in an argument to a non-allowlisted tool, the call is rejected with an error message directing you to store the value in the parameter store instead.

If you have already shared a credential in chat, rotate it immediately in the issuing system (GitHub settings, OpenAI dashboard, your database console) before doing anything else.

Secrets Guidance from the AI Agent

When you ask the OSC AI agent how to store a credential, or when it detects credential-shaped content in your message, it automatically calls the get-secrets-guide tool to provide a complete, authoritative reference on safe secret storage. The guide covers the parameter store approach for My App and Agent Tasks, service secrets for catalog services, and step-by-step instructions.

Security Hints from describe-service-instance

When you use the describe-service-instance MCP tool to inspect a running instance, any sensitive fields (API keys, passwords, tokens) that are stored as plaintext — rather than as {{secrets.name}} references — are flagged with a Security Recommendation in the response. The recommendation names the specific fields and explains how to use create-service-secret and the {{secrets.NAME}} syntax to move them to secure storage.

MCP Auto-Vault

When you use OSC MCP tools to create service instances, sensitive parameters (such as passwords and API keys) are automatically stored as secrets and referenced via {{secrets.name}} rather than being stored in plaintext. This happens without any extra steps on your part.

For example, if you ask an AI agent connected to OSC to create a CouchDB instance and provide an admin password, the MCP tool vaults the password as a Service Secret and stores the {{secrets.name}} reference in the instance configuration. The plaintext value is never written to instance parameters directly.

This means you do not need to manually create secrets before deploying services with sensitive configuration via MCP. The auto-vault behaviour applies to fields that OSC identifies as sensitive (passwords, API keys, tokens, and similar credential fields). Non-sensitive parameters such as port numbers, region selections, and display names are stored as plain values as before.

If you later need to rotate the secret value, use the Edit button on the Service Secrets tab for that service as described above in Modify a secret.

Related Resources

• User Guide: Secrets vs Parameter Store - Choosing the right primitive for credentials
• User Guide: Parameter Store - Setting up and managing a parameter store for runner workloads