Variables and Secrets
=====================

OneByZero Neo provides two mechanisms for storing configuration data that agents use at runtime: **Variables** for general configuration values, and **Secrets** for sensitive credentials. Both are managed in Workspace Settings and are available to agents scoped to the workspace.

Variables
---------

Variables are key-value pairs that agents can reference during execution. They are well suited for configuration values that may change between environments or that you want to manage centrally rather than hardcoding into individual agents.

.. image:: /images/admin-variables.png
   :alt: Workspace variables list
   :align: center
   :width: 70%

|

The variables list shows:

- **Name** — the variable name, used to reference the value in agents (e.g., ``AgenticFlowBaseUrl``, ``api_key``)
- **Agent Type** — which agent types can access this variable (e.g., Chat)
- **Type** — the data type (e.g., String)
- **Value** — the stored value; sensitive values are masked with asterisks

**Creating a Variable**

Click **+ Create** and fill in:

1. A descriptive name following a consistent naming convention
2. The agent type that should have access
3. The data type
4. The value

Common uses for variables:

- **API endpoints** — store base URLs for external services (e.g., ``AgenticFlowBaseUrl``)
- **API keys** — authentication keys for third-party services where full vault storage is not required
- **Environment configuration** — values that differ between staging and production
- **Integration parameters** — connection details for enterprise systems

**Managing Variables**

Use the Actions menu to edit a variable's value or delete it. Changes take effect the next time an agent that references the variable runs.

Secrets
-------

Secrets are for sensitive credentials — passwords, tokens, and keys — that require stricter handling. Unlike variables, secrets are stored in a vault backend and are never displayed in plain text in the UI after initial creation.

.. image:: /images/admin-secret.png
   :alt: Workspace secrets list
   :align: center
   :width: 70%

|

The secrets list shows:

- **Secret Name** — a descriptive name for the credential (e.g., ``remote-access-key``)
- **Reference** — the vault path agents use to access the secret (e.g., ``[[/secret/vault/pairing/remote-access-key]]``)
- **Created At** — when the secret was stored

**Creating a Secret**

Click **+ Create**:

1. Provide a name that identifies what the credential is for
2. Enter the secret value — this is the only time the plaintext value is visible
3. The system generates a reference path; copy it for use in agent configuration

Agents reference a secret using its vault path rather than the raw value. This means the secret value is never embedded in the agent's configuration directly.

**When to use Secrets vs Variables**

Use **Secrets** for anything that must not be visible in the UI after creation: database passwords, service account tokens, API keys for high-value services, and encryption keys.

Use **Variables** for configuration values that are not sensitive — base URLs, feature flags, timeout thresholds — where visibility in the admin UI is acceptable.

Rotate secrets whenever a team member with access leaves the organisation or when there is any suspicion of exposure.

Best Practices
--------------

**Naming conventions for variables**
   Use a consistent naming pattern — for example, ``SCREAMING_SNAKE_CASE`` for variables and prefixes that group related values (e.g., ``SALESFORCE_BASE_URL``, ``SALESFORCE_API_KEY``). This makes it clear at a glance what each variable is for and which integration it belongs to.

**Secrets for anything sensitive**
   If a value would cause harm if exposed in a browser session or log file — use a Secret, not a Variable. API keys for paid external services, database passwords, and service account tokens all belong in Secrets.

**Rotate on personnel changes**
   Rotate any Secrets that a departing team member had access to. Secrets do not expire automatically — rotation is a manual process that should be part of your offboarding checklist.