Documentation
Everything you need to know about using PlainVault.
What is PlainVault?
PlainVault is a secure internal vault for teams to store and share secrets, configuration files, and secure notes. All content is encrypted with AES-256-GCM and access is controlled by role-based permissions.
Common use cases:
- Database connection strings and credentials
- API keys for third-party services
- Environment variable configurations (env files)
- SSL certificates and private keys
- Team notes with sensitive information
- Infrastructure configuration (docker-compose, kubernetes configs)
How access works
Request an account from your administrator — go to the registration page and fill in your name, email, and password
Wait for approval — your administrator will receive your request and approve or reject it. You cannot log in until your account is activated.
Sign in and start managing files — once approved, log in and browse, create, or edit vault files based on your role
New to PlainVault? Check out the Get Started guide for installation instructions.
Roles & Permissions
PlainVault uses three roles with progressively scoped access. Administrators assign roles during user approval.
| Feature | ADMIN | DEVELOPER | VIEWER |
|---|---|---|---|
| View file (raw) | ✓ | ✓ | ✗ |
| View file (masked) | ✓ | ✓ | ✓ |
| Create file | ✓ | ✓ | ✗ |
| Edit file | ✓ | ✓ | ✗ |
| Delete file | ✓ | ✗ | ✗ |
| Manage categories | ✓ | ✗ | ✗ |
| Approve/reject users | ✓ | ✗ | ✗ |
| Create/revoke API keys | ✓ | ✗ | ✗ |
| View audit logs | ✓ | ✗ | ✗ |
| View revision history | ✓ | ✓ | ✗ |
ADMIN
Full access to all features. Manages files, categories, users, API keys, and audit logs. Can approve or reject new user registrations and revoke access at any time.
DEVELOPER
Can create and edit files, use API keys for programmatic access, and view revision history. Cannot delete files or manage users and categories.
VIEWER
Read-only access with automatic secret masking. Sensitive values like KEY=value are displayed as KEY=********. Ideal for auditors and stakeholders.
File Management
Files are the core unit in PlainVault. Each file stores encrypted content with a title, filename, and content type.
Creating a File
- Navigate to the Dashboard
- Click the "New File" button
- Enter a title (human-readable display name)
- Set a file name (e.g.
.env.production) - Choose a content type — this affects how secrets are masked
- Optionally assign a category for organization
- Paste or type your content and click Save
Viewing a File
- Click any file title in the dashboard list to open its detail page
- DEVELOPER / ADMIN — sees full raw content with all values visible
- VIEWER — sees masked content where sensitive values are replaced with
******** - Click the "RAW" button to view unformatted content (DEVELOPER/ADMIN only)
Editing a File
- Open the file detail page and click "Edit"
- Modify the content in the editor
- Enter a change summary (required) — describe what changed and why
- Click Save — a new revision is automatically created
Every edit creates a new revision. The previous version is never lost and can be restored from History.
Deleting a File
- Only ADMIN role can delete files
- Open the file detail page and click "Delete"
- Confirm the deletion in the dialog
Content Types
The content type determines how PlainVault masks sensitive values for VIEWER users:
| Type | Masking Behavior |
|---|---|
| env | Masks KEY=value pairs line by line |
| text | Masks KEY=value pairs line by line (same as env) |
| json | General pattern detection for sensitive values (keys, tokens, URLs) |
| yaml | General pattern detection for sensitive values (keys, tokens, URLs) |
| xml, sql, markdown | General pattern detection for sensitive values (keys, tokens, URLs) |
Categories
Organize files with color-coded labels. Only ADMIN can create, edit, and delete categories.
Managing Categories
- Click your role badge in the top-right corner → Categories
- Click "New Category"
- Enter a descriptive name (e.g. "Production", "AWS Credentials")
- Pick a color to visually distinguish it in the file list
- Click Create
Assigning Files to Categories
- When creating a file — select a category from the dropdown
- When editing a file — change the category in the edit form
- Files can exist without a category (uncategorized)
- Use the category chips above the file list to filter by category
Search & Filter
Find files quickly using text search and category filters.
Text Search
Type in the search bar at the top of the files list to filter by title or file name. Results update as you type — no need to press Enter.
Category Filter
Click a colored category chip above the file list to show only files in that category. Click "All" to clear the filter and show every file.
Combined Filters
Text search and category filters work together. For example, search for "api" while filtering by "Production" to find production API-related files.
History & Revisions
Every file edit creates a revision. Browse, compare, and restore previous versions.
Browsing Revisions
- Open a file detail page
- Click the "History" button
- A timeline of all revisions appears, newest first
- Click any revision to view its full content
Only DEVELOPER and ADMIN roles can access revision history.
Comparing Revisions
- Open the revision history panel
- Click one revision to select it
- Cmd+Click (Mac) or Ctrl+Click (Windows/Linux) to select a second revision
- Click "Compare" to see the diff
The diff view shows:
+ Added line here
- Removed line here
Unchanged line
Restoring a Previous Version
- Open the revision you want to restore
- Click "Restore" to apply it as the current version
- Enter a change summary (e.g. "Reverted to v3 config")
- The restoration itself creates a new revision — the history is never lost
API Keys
Access files programmatically via REST API using bearer token authentication. Only ADMIN can create and revoke keys.
Creating an API Key
- Click your role badge in the top-right corner → API Keys
- Click "Create Key"
- Give it a descriptive name (e.g. "CI/CD Pipeline", "Dev Environment")
- Optionally set an expiration date
- Click Create — the key is displayed only once
Using API Keys
Include the key in the Authorization header of your HTTP requests:
Authorization: Bearer secvault_abc123
Scopes:
files:read— list files and read metadata/contentfiles:write— create and update filesfiles:read_raw— download raw decrypted content
Example with curl:
curl -H "Authorization: Bearer your_key_here" \
http://localhost:13000/api/v1/files/{id}/raw
Revoking a Key
- Navigate to API Keys from the admin menu
- Find the key you want to revoke
- Click "Revoke"
- The key is immediately invalidated — any requests using it will be rejected
Security
How PlainVault protects your data.
Encryption at Rest
All file content is encrypted with AES-256-GCM before being stored in the database. Each file uses a unique salt and IV derived from a master key via PBKDF2 (100,000 iterations). Even if the database is compromised, content cannot be read without the encryption key.
Secret Masking
VIEWER role users see automatically masked content. Sensitive patterns like KEY=value are replaced with KEY=********.
Raw (DEVELOPER / ADMIN)
DATABASE_URL=postgres://user:secret@db:5432
API_KEY=sk_live_abcdef123456
Masked (VIEWER)
DATABASE_URL=********
API_KEY=********
API Key Security
- API keys are hashed with SHA-256 before storage — the raw key is never stored in the database
- Keys are displayed only once at creation time
- Keys can have an optional expiration date
- Revoked keys are immediately invalidated
Audit Trail
Every action is logged for compliance and security reviews. The audit trail captures:
- User login and logout events
- File creation, viewing, editing, and deletion
- Category management operations
- User approval and rejection decisions
- API key creation and revocation
Only ADMIN role can view audit logs.