Credential Folders

Overview

Credential folders provide hierarchical organization for the credentials stored in the Credential Vault. Folders let you group credentials by environment (production, staging, development), by function (core routers, firewalls, switches), by site (DC1, DC2, branch offices), or any other organizational structure that matches your team's workflow.

Beyond organization, folders are the primary mechanism for access control. Credentials inherit their access permissions from the folder they belong to. When you grant a role access to a folder, all members of that role can use the credentials in that folder and its sub-folders. This eliminates the need to manage permissions on individual credentials.

• Hierarchical folder structure with unlimited nesting depth
• Role-based access grants per folder with can_view_password control
• Permission cascading from parent folders to sub-folders
• Folder-level audit logging for all access and modification events
• Move credentials between folders to change their access scope

How It Works

Folder Hierarchy

Folders can be nested to any depth, creating a tree structure. A common pattern is to organize by environment at the top level, then by device function or site at lower levels:

Credential Vault
├── Production
│   ├── Core Routers
│   ├── Distribution Switches
│   ├── Firewalls
│   └── WAN Edge
├── Staging
│   ├── Lab Devices
│   └── Test Firewalls
├── Development
│   └── Dev Switches
└── Shared Services
    ├── DNS/DHCP
    └── Load Balancers

Role-Based Access

Each folder has an access control list that maps roles to permission grants. A grant specifies two things:

• Access — Members of the role can use credentials in this folder for device connections. The Controller decrypts and uses the credential on their behalf without exposing the raw value.
• Password visibility (can_view_password) — Whether members can reveal the raw credential value in the UI. This creates an audit log entry. Typically enabled only for senior engineers or credential administrators.

Permission Cascading

When you grant a role access to a folder, that access extends to all sub-folders automatically. For example, granting the "Network Operators" role access to the "Production" folder gives them access to credentials in "Production/Core Routers", "Production/Firewalls", and all other sub-folders under Production.

Audit Logging

Every folder operation generates an audit log entry: folder creation, deletion, renaming, access grants, access revocations, and credential moves. These logs provide a complete history of how access to credentials has changed over time.

Step-by-Step Guide

Step 1: Create a Top-Level Folder

1. Navigate to Credentials in the Admin UI
2. Click New Folder
3. Enter a name (e.g., "Production")
4. Optionally add a description
5. Leave Parent Folder blank for a top-level folder
6. Click Create

Step 2: Create Sub-Folders

1. Click New Folder again
2. Enter a name (e.g., "Core Routers")
3. Select Production as the parent folder
4. Click Create
5. Repeat for other categories: "Firewalls", "Distribution Switches", etc.

Step 3: Move Credentials into Folders

1. Navigate to Credentials and find the credential to organize
2. Click Edit on the credential
3. In the Folder dropdown, select the target folder
4. Click Save
5. The credential now inherits the access permissions of its new folder

Step 4: Share a Folder with a Role

1. Navigate to the folder and click Folder Settings or the gear icon
2. Go to the Access tab
3. Click Add Role
4. Select the role (e.g., "Network Operators")
5. Optionally enable Can View Password
6. Click Grant Access

Step 5: Set Folder-Level Permissions

Fine-tune access for different teams:

1. Grant "Network Operators" access to "Production" with password viewing disabled
2. Grant "Senior Engineers" access to "Production" with password viewing enabled
3. Grant "Security Team" exclusive access to "Production/Firewalls"
4. Each role sees only the folders they have been granted access to

Code Examples

Create a Folder via API

# Create a top-level folder
curl -X POST https://controller.example.net/api/credential-folders \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "description": "All production network device credentials"
  }'

# Create a sub-folder under Production
curl -X POST https://controller.example.net/api/credential-folders \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Core Routers",
    "description": "Core routing infrastructure credentials",
    "parent_id": "folder-uuid-of-production"
  }'

Grant Role Access to a Folder

# Grant the Network Operators role access to the Production folder
curl -X POST https://controller.example.net/api/credential-folders/folder-uuid/access \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "role-uuid-network-operators",
    "can_view_password": false
  }'

# Grant Senior Engineers access with password viewing
curl -X POST https://controller.example.net/api/credential-folders/folder-uuid/access \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "role-uuid-senior-engineers",
    "can_view_password": true
  }'

Move a Credential to a Different Folder

# Update a credential's folder assignment
curl -X PATCH https://controller.example.net/api/credentials/credential-uuid \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "new-folder-uuid"
  }'

List Credentials in a Folder

# List all credentials in a folder (and its sub-folders)
curl https://controller.example.net/api/credentials?folder_id=folder-uuid \
  -H "Authorization: Bearer ${API_TOKEN}"

# Response:
# {
#   "credentials": [
#     {
#       "id": "cred-uuid-1",
#       "name": "Core Router Admin - DC1",
#       "credential_type": "ssh_password",
#       "folder_id": "folder-uuid",
#       "username": "admin"
#     },
#     {
#       "id": "cred-uuid-2",
#       "name": "Automation Key - DC1",
#       "credential_type": "ssh_key",
#       "folder_id": "folder-uuid",
#       "username": "netops"
#     }
#   ]
# }

Questions & Answers

Q: How do I create a credential folder?

A: Navigate to Credentials in the Admin UI, click New Folder, enter a name and optional description, select a parent folder (or leave blank for top-level), and click Create. Folders can also be created via the API by posting to the credential-folders endpoint.

Q: How do permissions cascade through folders?

A: When you grant a role access to a folder, that access automatically extends to all sub-folders. For example, granting access to "Production" gives access to "Production/Core Routers" and every other folder under Production. You can override this by setting more restrictive grants on specific sub-folders.

Q: Can I share a folder with multiple roles?

A: Yes. Each folder can have multiple role grants. You can grant different permission levels to different roles — for example, "Network Operators" can use credentials but not view passwords, while "Senior Engineers" can both use and view passwords.

Q: How do I move credentials between folders?

A: Edit the credential and change its folder assignment, or use the API to update the folder_id field. Note that moving a credential changes its access scope — only users with access to the new folder can use it.

Q: Is there a maximum folder nesting depth?

A: There is no hard limit on folder nesting depth. However, for practical usability, three to four levels of nesting is recommended (e.g., Environment → Site → Device Function). Deeply nested folders become harder to navigate and manage.

Q: Can I delete a folder that contains credentials?

A: No. A folder must be empty before it can be deleted. Move or delete all credentials in the folder first, then delete any empty sub-folders, and finally delete the parent folder. This prevents accidental deletion of credentials.

Troubleshooting

Permission denied on folder access

If a user cannot see or use credentials in a folder:

• Verify the user's role has been granted access to the folder (check Folder Settings → Access)
• Check if the grant exists on a parent folder (permissions cascade down, not up)
• If the user was recently assigned a new role, they may need to log out and back in for role changes to take effect

Folder not visible in the UI

Folders are only visible to users whose roles have been granted access:

• A folder with no role grants is visible only to administrators
• If a user cannot see a folder, an administrator must grant their role access
• Check the folder's access grants to see which roles have access

Cannot delete non-empty folder

Folders must be empty before deletion:

1. List all credentials in the folder
2. Move credentials to another folder or delete them
3. Check for and empty any sub-folders
4. Delete empty sub-folders first (bottom-up)
5. Then delete the parent folder

# List credentials in a folder to find what needs to be moved
curl https://controller.example.net/api/credentials?folder_id=folder-uuid \
  -H "Authorization: Bearer ${API_TOKEN}"

# Move credentials to a different folder
curl -X PATCH https://controller.example.net/api/credentials/credential-uuid \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "destination-folder-uuid"}'

# Delete the now-empty folder
curl -X DELETE https://controller.example.net/api/credential-folders/folder-uuid \
  -H "Authorization: Bearer ${API_TOKEN}"

Related Features

Explore related credential and access management features:

• Credential Vault — How credentials are encrypted and stored
• Personal Vaults — Per-user private credential storage outside the folder hierarchy
• Roles & Permissions — Configure the roles that are granted access to credential folders
• User Management — Manage users and their role assignments
• Audit Logs — Review folder access grants, revocations, and credential movements