Enterprise Secrets Management

Store and use personal and organization-wide secrets in OpenHands Enterprise.

OpenHands Enterprise stores credentials for agents to use in conversations and automations. Use personal secrets for an individual’s access and organization secrets for credentials shared by a team. For example, an Admin can save a service account token once so organization members can use it without entering separate copies.

How Secrets Are Stored

Custom secret values are encrypted by the application before they are saved in the Enterprise database. The application decrypts them when loading secrets for an agent runtime. Encryption at rest protects the stored values; authorized runtimes still need the credentials to call external services.

The secrets settings and management APIs show names and descriptions, not saved values. This also applies to organization Admins and Owners and the person who created a secret. Descriptions are provided to the agent, so keep credential values out of names, descriptions, and prompts.

Scope and Permissions

An organization secret belongs to one OpenHands organization. It is available to that organization’s members, including new members, and is not automatically shared with other organizations on the same Enterprise instance. A personal secret is private to its creator within the selected organization.

Action	Member	Admin or Owner
List shared secrets and your own personal secrets (names and descriptions)	Yes	Yes
Create, edit, or delete your own personal secrets	Yes	Yes
Use shared secrets in conversations and automations	Yes	Yes
Create, edit, or delete shared secrets	No	Yes
Read saved values in settings or the management API	No	No

Shared secrets are delivered to members’ agent runtimes so their tools can use them. Hiding saved values in settings does not prevent code running in those runtimes from accessing the credentials. Share credentials intended for use by every member of the organization.

Create an Organization Secret

1. Select the organization that should own the secret.
2. As an Admin or Owner, open Settings > Secrets.
3. Select Add a new secret.
4. Enter a name, value, and optional description. Names must start with an ASCII letter or underscore and contain only ASCII letters, digits, and underscores, such as TEAM_SERVICE_TOKEN.
5. Check Share with organization.
6. Select Add secret.

The secret appears under Organization secrets. Members can see its name and description and use it in new conversations. Members cannot edit or delete it. Leave Share with organization unchecked when creating a personal secret.

A secret’s scope is set at creation. Do not change the Share with organization checkbox while editing: it does not convert an existing secret between personal and shared scope. Create a secret in the intended scope and remove the old one when it is no longer needed.

Use Shared Secrets

By default, shared secrets are loaded alongside the user’s personal secrets for the conversation’s organization. The agent’s terminal exports a secret into the shell when the command text references its name. For a script that reads the variable internally, name it explicitly in the command:

TEAM_SERVICE_TOKEN=$TEAM_SERVICE_TOKEN python deploy.py

Running only python deploy.py does not trigger that export. Matching is case-insensitive and uses substrings, so prefer specific names over short, generic names such as TOKEN. Once exported, the variable persists in that terminal session. Refer to the secret by name without putting its value in a prompt.

Automations can use shared secrets from their organization. They still run as their creating user; adding a shared credential does not change the automation’s run identity.

When both scopes are loaded, use distinct names for personal and shared secrets. If both have the same name, the personal secret keeps the original environment variable name and the shared secret receives an available suffix, such as TEAM_SERVICE_TOKEN_2. Avoid relying on a suffixed name that can differ between members.

For credentials needed by one conversation, you can pass secrets at conversation start. They override stored secrets with the same permitted name for that conversation and are still subject to the Agent Profile’s secret selection.

Agent Profile Secret Selection

This section applies to deployments using Agent Profiles through an enabled UI or the API. Enterprise package 0.94.0 (server 1.83.0) includes the profile API, but the personal and organization profile-management UIs are disabled by default. Organization secrets do not require enabling those UIs. Check your deployment’s version and configuration before following profile-specific guidance.

An Agent Profile with an explicit secret list filters the assembled conversation secrets to the listed names. An empty list selects none; a profile without an explicit list keeps the default set. OpenHands can then register credential-helper access tokens for output masking, even when their names are absent from the list.

• An organization-scoped profile can select only organization-shared secrets. Personal secrets are excluded, and selected shared secrets retain their original names.
• A personal profile also filters by its selected names. Add a newly shared secret to that list before expecting conversations using the profile to receive it.
• The final filter also applies to conversation-start secrets and provider tokens such as GITHUB_TOKEN. It does not preserve OPENHANDS_API_KEY when that name is absent from the list. A sandbox credential helper may still authenticate Git operations independently of whether GITHUB_TOKEN is selected.

This selection controls the conversation secret registry; it does not revoke credentials already delivered to a runtime or separately installed for a sandbox credential helper.

Edit, Rotate, or Delete a Secret

Admins and Owners can edit a shared secret’s name and description or delete it from Settings > Secrets. The edit form does not replace its value.

Renaming changes the environment variable name. Update tools, automations, and any Agent Profiles used by your deployment that reference the old name. Renaming or deleting a shared secret does not rewrite organization profile references: a later launch can continue without that missing credential, with a server-side warning.

Personal Secrets

To replace your own personal secret’s value in the UI, delete it and add it again with the same name and new value. The add form rejects duplicate names. Through the API, POST /api/v1/secrets with the same name overwrites your personal value without deleting it first. The organization value endpoints below target shared secrets only; a personal secret alone does not satisfy that lookup.

Shared Secrets

To replace a value through the UI, delete the shared secret and create it again with the new value. The secret is unavailable between those steps. To replace the stored value without deleting it, check that your deployment’s /openapi.json lists both dedicated value-replacement endpoints before using this API flow:

1. Read GET /api/organizations/{org_id}/secrets/{secret_name}/version.
2. Send PUT /api/organizations/{org_id}/secrets/{secret_name}/value with the new value, the returned version as expected_version, and a fresh UUID as request_id.

Authenticate with an OpenHands API key for an Admin or Owner in the target organization. If the key is organization-bound, its organization must match ORG_ID. Set OH_BASE_URL, ORG_ID, and OH_API_KEY for your deployment, then read the current version:

curl --fail --silent --show-error \
  "$OH_BASE_URL/api/organizations/$ORG_ID/secrets/TEAM_SERVICE_TOKEN/version" \
  -H "Authorization: Bearer $OH_API_KEY"

Create a private replacement.json file with the new value, the UUID returned by that GET, and a fresh UUID for this replacement’s request ID. Replace these illustrative fields before sending:

{
  "value": "NEW_SECRET_VALUE",
  "expected_version": "VERSION_UUID_FROM_GET",
  "request_id": "FRESH_REQUEST_UUID"
}

chmod 600 replacement.json
curl --fail --silent --show-error -X PUT \
  "$OH_BASE_URL/api/organizations/$ORG_ID/secrets/TEAM_SERVICE_TOKEN/value" \
  -H "Authorization: Bearer $OH_API_KEY" \
  -H "Content-Type: application/json" \
  --data @replacement.json

Do not log the request body or commit the file. Keep the original request privately until its outcome is known, then remove the local credential file when it is no longer needed.

Value replacement requires Admin or Owner permissions. If a response is lost, retry the identical request. A 409 means the operation conflicts with the current state; reconcile before attempting another replacement.

Start new conversations after changing a secret. Running conversations may retain previously delivered values. Replacing or deleting a stored secret does not revoke the credential at its external provider or erase copies already delivered to a runtime.

Sync From an External Secrets Manager

You can keep an external secrets manager as the source of truth and synchronize selected values into OpenHands through its secrets APIs. The sync process writes encrypted copies into OpenHands; this is not a live reference to the external vault.

See AWS Secrets Sync in the Enterprise Cookbook for a script that maps AWS Secrets Manager values to personal or organization secrets, detects source rotation, and tracks sync progress. You run and schedule the script. The example also explains how to adapt its source reader to another secrets manager and documents its compatibility and recovery limits.

The example rotates shared values by deleting and re-creating them with --allow-delete-recreate; it does not use the value-replacement API above. The secret is unavailable between those steps, and an interrupted sync can leave it missing until recovery completes.

Next Steps

• Secrets Management for Individual Users - Add and use personal secrets.
• Roles and Permissions - Manage access within an organization.
• AWS Secrets Sync - Synchronize credentials from an external source.