Personal Vaults

Overview

Personal vaults provide per-user private credential storage that is completely separate from the shared organizational Credential Vault. Every user in NetStacks has their own personal vault where they can store SSH keys, passwords, and other credentials that are accessible only to them.

Personal vaults are designed for credentials that should not be shared with the broader team: an individual engineer's personal SSH key for lab devices, device-specific passwords for equipment under a single person's responsibility, or temporary credentials for troubleshooting sessions.

• Per-user private storage — only the owning user can access their personal credentials
• Same AES-256-GCM encryption as the shared vault
• Cannot be assigned to folders (personal credentials exist outside the folder hierarchy)
• View/reveal permissions controlled by administrators
• Personal credentials can be used for device connections just like shared credentials
• Separate from shared vault — personal credentials do not appear in team views

How It Works

Isolation from the Shared Vault

Personal vault credentials are stored in the same database table as shared credentials but are distinguished by an owner_id field. When a credential has an owner_id, it is a personal credential belonging to that user. The Controller enforces strict ownership: API queries for personal credentials always filter by the authenticated user's ID, and no other user (including administrators) can use another user's personal credentials for device connections.

Encryption

Personal vault credentials use the same AES-256-GCM encryption as shared credentials. The vault master key (derived via Argon2id from VAULT_MASTER_KEY) encrypts all credentials uniformly. There is no per-user key derivation — isolation is enforced at the access control layer, not the encryption layer.

View/Reveal Permissions

By default, users can use their personal credentials for connections (the Controller decrypts and uses them on the user's behalf) but cannot reveal the raw credential values. Administrators can configure whether the reveal action is available for personal vault credentials. Even when reveal is enabled, every reveal action creates an audit log entry.

Ownership and Lifecycle

Personal credentials are tied to the user's account. If a user account is deactivated, their personal credentials remain in the database but become inaccessible. If the account is reactivated, the credentials are available again. If the account is permanently deleted, personal credentials are deleted with it.

Step-by-Step Guide

Step 1: Access Your Personal Vault

1. Navigate to Credentials in the Admin UI
2. Click the Personal Vault tab (next to the Shared Vault tab)
3. Your personal vault shows only credentials you own
4. Other users cannot see this view or the credentials in it

Step 2: Add a Personal Credential

1. In the Personal Vault tab, click Add Credential
2. Select a credential type (SSH Password, SSH Key, etc.)
3. Enter the credential details
4. Note: there is no folder selection — personal credentials do not use folders
5. Click Save

Step 3: Use a Personal Credential When Connecting

1. Open the Terminal and initiate a connection to a device
2. In the credential selection dialog, you will see both shared credentials (from folders you have access to) and your personal credentials
3. Personal credentials are labeled with a "Personal" badge
4. Select the personal credential and connect
5. The Controller decrypts your personal credential and uses it for the session

Step 4: Configure View/Reveal Permissions (Admin)

1. Navigate to Administration → System Settings
2. Under Credential Settings, find the personal vault reveal option
3. Enable or disable the ability for users to reveal their own personal credential values
4. When disabled, users can use personal credentials for connections but cannot see the raw values

Step 5: Delete a Personal Credential

1. Navigate to your Personal Vault
2. Find the credential to delete
3. Click Delete and confirm
4. The encrypted credential is permanently removed from the database
5. Any devices that were using this credential will need a new credential assigned

Code Examples

List Personal Vault Credentials

# List credentials in your personal vault
curl https://controller.example.net/api/credentials/personal \
  -H "Authorization: Bearer ${API_TOKEN}"

# Response:
# {
#   "credentials": [
#     {
#       "id": "pv-cred-uuid-1",
#       "name": "Lab Switch SSH Key",
#       "credential_type": "ssh_key",
#       "username": "jsmith",
#       "owner_id": "user-uuid",
#       "folder_id": null,
#       "created_at": "2025-01-20T14:30:00Z"
#     },
#     {
#       "id": "pv-cred-uuid-2",
#       "name": "Dev Firewall Admin",
#       "credential_type": "ssh_password",
#       "username": "admin",
#       "owner_id": "user-uuid",
#       "folder_id": null,
#       "created_at": "2025-02-10T09:15:00Z"
#     }
#   ]
# }

Create a Personal Credential

# Create a personal SSH key credential
curl -X POST https://controller.example.net/api/credentials/personal \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Lab SSH Key",
    "description": "Personal Ed25519 key for lab environment",
    "credential_type": "ssh_key",
    "username": "jsmith",
    "secret": "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEA...\n-----END OPENSSH PRIVATE KEY-----",
    "metadata": {
      "key_type": "ed25519",
      "environment": "lab"
    }
  }'

# Note: no folder_id is provided or accepted for personal credentials

Use a Personal Credential in a Device Connection

# When connecting to a device, you can specify a personal credential
# The Controller verifies you own the credential before allowing use
curl -X POST https://controller.example.net/api/devices/device-uuid/connect \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "pv-cred-uuid-1"
  }'

# The Controller:
# 1. Verifies the credential's owner_id matches the authenticated user
# 2. Decrypts the credential in memory
# 3. Establishes the SSH session
# 4. Discards the decrypted value

Questions & Answers

Q: What is a personal vault?

A: A personal vault is a per-user private credential storage area within NetStacks. Every user has their own personal vault where they can store credentials that are accessible only to them. Personal vault credentials are encrypted with the same AES-256-GCM encryption as the shared vault.

Q: How does the personal vault differ from the shared vault?

A: The shared vault uses credential folders with role-based access grants, allowing teams to share credentials. The personal vault is private to a single user — no other user can access, view, or use your personal credentials. Personal credentials cannot be placed in folders and do not appear in team views of the credential list.

Q: Can administrators see my personal credentials?

A: Administrators can see that personal credentials exist (for audit and compliance purposes) but cannot use them for device connections or view the raw values. The Controller enforces ownership by filtering on the authenticated user's ID for all credential use operations.

Q: Can I share a personal credential with another user?

A: No. Personal credentials are strictly private. If you need to share a credential, create it in the shared vault and place it in a folder with appropriate role-based access. Personal credentials cannot be moved to folders or transferred to other users.

Q: What happens to my personal vault when my account is deactivated?

A: When your account is deactivated, your personal credentials remain encrypted in the database but become inaccessible. No one can use them. If your account is reactivated, the credentials become available to you again. If your account is permanently deleted, all personal credentials are deleted with it.

Q: How is my personal vault encrypted?

A: Personal vault credentials use the same AES-256-GCM encryption and Argon2id-derived master key as all other credentials in the vault. Isolation between users is enforced at the access control layer (ownership checks), not at the encryption layer. All credentials share the same master encryption key.

Troubleshooting

Cannot access personal vault

If you cannot see or access the Personal Vault tab:

• Verify your account is active and you can log in normally
• Check that the personal vaults feature is enabled by your administrator (System Settings → Credential Settings)
• Try logging out and back in to refresh your session

Personal credential not appearing in connection dialog

If your personal credential does not appear when connecting to a device:

• Verify the credential type matches the connection type (e.g., SSH key for SSH connections)
• Check that the credential has not expired (expires_at field)
• Confirm you are logged in as the user who owns the credential
• Personal credentials may not appear if the device already has a mandatory shared credential assigned

Reveal permission denied

If you cannot reveal the raw value of your own personal credential:

• Your administrator may have disabled the reveal feature for personal vaults
• Contact your administrator to enable the reveal option in System Settings
• You can still use the credential for connections without being able to see its value

Personal vault not available

If the Personal Vault feature is not available at all:

• The feature may need to be enabled by an administrator in System Settings
• Check that your NetStacks Controller is running a version that supports personal vaults
• Contact your administrator for assistance

Related Features

Explore related credential management features:

• Credential Vault — The shared organizational vault with AES-256-GCM encryption
• Credential Folders — Organize shared credentials with hierarchical folders and role-based access
• SSH Passwords & Keys — Store personal SSH keys or password credentials in your vault
• User Management — Manage user accounts that own personal vaults
• Adding Devices — Use personal credentials when connecting to devices