Secrets

OnePAM-managed

The encrypted payload is stored in the OnePAM cloud. This is the simplest option and requires no additional setup.

Customer-managed (Gateway)

The encrypted payload is stored on your dedicated gateway. Requires at least one registered dedicated gateway. Secrets are stored and resolved within your own network.

Agent-managed

The encrypted payload is stored exclusively on the agent host. Secrets are created and managed directly on the server via the agent CLI — no one else can modify them. Only the secret title (name and type) is synced to OnePAM so administrators can assign agent-managed secrets to resources. OnePAM never sees credential values.

• Create — click New Secret, choose a type and storage mode, enter values, and save.
• View — click a secret to see its metadata and access log. Click Reveal to decrypt and display values (this action is audited).
• Assign — secrets are assigned to resources from the resource create/edit form or via bulk operations.
• Delete — removes the secret metadata and stored payload. Assigned resources will lose their credential binding.

The Access Log tab on each secret shows a chronological history of who accessed or revealed the secret.

Agent-managed secrets are credentials created and stored exclusively on the agent host. Unlike OnePAM-managed or gateway-managed secrets, agent-managed secrets can only be created, modified, or deleted by an operator with access to the agent's host machine. The onepam.com API and web UI cannot modify them.

How It Works

1. An operator runs onepam-agent --secrets add on the agent host to create a secret.
2. The secret is encrypted with AES-256-GCM and stored in secrets.enc in the agent's data directory.
3. The agent automatically syncs secret titles (ID, name, type) to onepam.com — credential values are never transmitted.
4. Administrators can then assign agent-managed secrets to resources via the UI or CLI.
5. At session time, the agent resolves the credential locally from its encrypted store.

Ownership Model

Run these commands on the agent host to manage local secrets. All commands use the agent's data directory (/opt/onepam/data by default).

List local secrets

onepam-agent --secrets list

Add a password credential

onepam-agent --secrets add \
  --secret-name "prod-db-admin" \
  --secret-username "admin" \
  --secret-password "s3cur3-p@ss"

Add an SSH key

onepam-agent --secrets add \
  --secret-name "deploy-key" \
  --secret-key-file ~/.ssh/id_rsa \
  --secret-passphrase "optional-passphrase"

Test secret resolution

onepam-agent --secrets test --secret-id <uuid>

Remove a secret

onepam-agent --secrets remove --secret-id <uuid>

Use the onepam CLI client to manage secrets from any workstation. These commands work with all storage modes (OnePAM, gateway, and agent-managed).

List all secrets

onepam secrets list

Create a new secret (OnePAM-managed)

onepam secrets create --name "staging-db" --type password

Show secret metadata

onepam secrets show <secret-id>

Reveal secret values (audited)

onepam secrets reveal <secret-id>

View access audit log

onepam secrets audit <secret-id>

List secrets on a specific agent

onepam secrets remote --agent-id <agent-uuid>

Delete a secret

onepam secrets delete <secret-id>

Assign a secret to a resource

onepam resources assign-secret <resource-name> <secret-id>

Remove a secret assignment

onepam resources unassign-secret <resource-name>

Any secret — regardless of storage mode — can be assigned to a resource. When a user connects to that resource, the agent automatically resolves the credential and injects it into the session.

Agent-Managed Secret Assignment Flow

1. The agent operator creates a secret on the host: onepam-agent --secrets add --secret-name "prod-db"
2. The agent syncs the secret title to onepam.com automatically.
3. An administrator assigns the secret to a resource via the UI or CLI: onepam resources assign-secret my-server <secret-id>
4. When a user connects, the agent resolves the credential from its local encrypted store and injects it.

Via the UI

Navigate to Resources, edit the target resource, and select the desired secret from the Secret dropdown. Agent-managed secrets appear alongside OnePAM-managed and gateway-managed secrets.

Via the API

POST /api/v1/resources/{id}/secret
Content-Type: application/json

{ "secret_id": "<secret-uuid>" }

Encryption at Rest

All secrets are encrypted using AES-256-GCM. The encryption key is derived via SHA-256 from one of:

• AGENT_SECRET_KEY environment variable (recommended for production)
• INTEGRATION_SECRET_KEY environment variable (fallback)
• An auto-generated 256-bit random key stored in <data-dir>/.secret_key (generated on first run)

The encrypted file (secrets.enc) is written atomically to prevent corruption.

Agent-Only Write Ownership

For agent-managed secrets, the agent is the sole authority for credential values. The onepam.com API enforces this with explicit guard rails:

• The Create endpoint rejects storage_mode: "agent" — agent secrets can only be created on the host.
• The Update and Store endpoints reject writes to any secret whose storage mode is agent.
• The Delete endpoint rejects deletion of agent-managed secret metadata — only the agent can remove them.
• The CLI client (onepam secrets) validates input format before sending requests, providing an additional layer of defense.

Only the operator on the agent host can mutate the encrypted store via onepam-agent --secrets.

Title Sync (Metadata Only)

When the agent creates or removes a secret, it syncs a list of titles (secret ID, name, and type) to onepam.com. This metadata enables resource assignment in the UI and API. Credential values — passwords, keys, passphrases — are never included in the sync.

• Signed requests — every sync request is signed with HMAC-SHA256 using the agent's encryption key, both in long-running mode and standalone CLI mode.
• Strict validation — secret IDs must be valid UUIDv4 and types must match the allowed set (credential, ssh_key, api_key, certificate, generic). Names are trimmed and length-limited (max 255 chars).
• Atomic upsert — all creates, updates, and deletes within a single sync run inside a database transaction. A partial failure rolls back the entire batch, preventing inconsistent state.
• Collision protection — onepam.com rejects any agent-reported secret ID that already belongs to an OnePAM-managed or gateway-managed secret, preventing cross-mode ID conflicts.
• Rate-limited — a single sync accepts at most 500 secrets.

Audit Trail

Every Reveal operation (decrypting and displaying a secret) is logged with the user identity, timestamp, client IP, and the resource context. Access logs are available per-secret and in the organisation-wide audit log.