Skip to content

Secrets Management

Creating, Sharing, Versioning, and Rotating Secrets

Document Version: 1.0.0
Last Updated: 2026-02-10

1. Secret Types

MazeVault supports the following secret types:

Type Description Use Case
password Passwords and passphrases Database credentials, service accounts
api_key API keys and tokens Third-party service integration
certificate TLS/SSL certificates with private keys Service-to-service encryption
ssh_key SSH key pairs Server access, Git authentication
generic Freeform key-value Configuration values, connection strings

2. Creating Secrets

Via Web Interface

  1. Navigate to Secrets → Select your project
  2. Click + New Secret
  3. Fill in the secret details:
  4. Name: Unique within the project (e.g., prod/database/master-password)
  5. Value: The secret value
  6. Type: Secret type
  7. Description: What this secret is for
  8. Tags: Organizational tags
  9. Optionally configure rotation:
  10. Enable Rotation: Toggle on
  11. Rotation Interval: Days between automatic rotations
  12. Click Create

Via API

curl -X POST https://vault.example.com/api/v1/secrets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod/database/master-password",
    "value": "s3cur3P@ssw0rd!",
    "project_id": "proj_abc123",
    "type": "password",
    "description": "Production database master password",
    "tags": ["production", "database"]
  }'

3. Secret Versioning

Every update to a secret creates a new version. The version history provides:

  • Audit trail — Who changed the secret and when
  • Rollback capability — Revert to any previous version
  • Change tracking — Whether the change was manual, rotation, or sync

Viewing Version History

  1. Navigate to the secret detail page
  2. Click the Versions tab
  3. View all versions with timestamps and change authors

Rolling Back

  1. In the version history, locate the desired version
  2. Click Rollback to this version
  3. Confirm the rollback

This creates a new version with the content of the selected historical version.

4. Secret Rotation

Manual Rotation

  1. Navigate to the secret detail page
  2. Click Rotate
  3. Enter the new secret value
  4. Click Confirm Rotation

Automated Rotation

Configure automatic rotation for secrets that need regular updates:

  1. Edit the secret → Rotation Settings
  2. Enable rotation
  3. Set the interval (e.g., 90 days)
  4. Save

The platform will automatically rotate the secret at the configured interval and notify connected agents.

Rotation Notifications

When a secret is rotated:

  • All agents with access receive the update within the sync interval
  • The audit log records the rotation event
  • Dashboard shows the next rotation date

5. Secret Sharing

Secrets are shared through project membership and RBAC roles:

Role Read Create Update Delete Rotate
Viewer ✅ — — — —
Editor ✅ ✅ ✅ — —
Manager ✅ ✅ ✅ ✅ ✅
Admin ✅ ✅ ✅ ✅ ✅

Sharing a Secret

  1. Ensure the target user is a member of the project
  2. Assign the appropriate role to the user
  3. The user can now access secrets according to their role

6. Secret Naming Conventions

We recommend organizing secrets with path-like naming:

<environment>/<service>/<name>

Examples:
prod/database/master-password
prod/api/stripe-key
staging/redis/auth-token
dev/aws/access-key

Using Tags

Tags provide additional organization:

Tag Purpose
production Production environment secrets
staging Staging environment secrets
database Database credentials
api-key Third-party API keys
rotate-90d Secrets requiring 90-day rotation

7. Secret Synchronization

For multi-datacenter deployments, secrets are synchronized automatically:

  • Sync Interval: Configurable (default: 5 minutes)
  • Conflict Resolution: Configurable per project (source wins / target wins / manual)
  • Sync Status: Visible on the secret detail page and dashboard

Check Sync Status

  1. Navigate to the secret detail page
  2. View the Sync section showing each datacenter's status
  3. Status values: synced, pending, conflict

Force Sync

If a secret is out of sync, force synchronization:

  1. Navigate to the secret detail page
  2. Click Force Sync
  3. The secret will be pushed to all configured targets