Vaults

Vaults in Kinesis API are secure storage containers for sensitive configuration data and secrets within a project. They provide encrypted storage for API keys, database credentials, tokens, and other sensitive information that your application needs to access securely.

Understanding Vaults

Vaults in Kinesis API work as key-value stores with built-in encryption. Each vault entry:

• Belongs to a specific project
• Contains a unique key identifier and an encrypted value
• Is encrypted at rest using the vault’s encryption system
• Can be accessed only by authorized project members
• Is isolated per project for security boundaries

Vaults serve as a centralized, secure location for managing sensitive configuration data used across your project’s collections and routes.

Accessing Vaults

Vaults can be accessed in two ways:

1. Via the Web Interface: Navigate to /web/vaults to view all projects with vault access, then select a project to manage its vault entries
2. Via the API: Use the vault endpoints with appropriate authentication and project membership

Vault Management Interface

The vault management interface (/web/vaults) provides access to all projects you have permission to manage:

• A filterable, paginated list of projects
• Quick access to project vault entries
• View and management of project members
• Ability to navigate to individual project vaults

Accessing Project Vaults

To access vaults for a specific project:

1. Navigate to /web/vaults in your browser
2. Filter or locate the project you want to manage
3. Click on the project name or the “View Vaults” button
4. You’ll be taken to the project vault page (/web/vault?project_id=[project_id])

The project vault page displays all vault entries for that project, allowing you to create, update, or delete entries.

Creating a Vault Entry

To create a new vault entry:

1. Navigate to the project vault page
2. Click the “Create New” button or the “+” icon
3. Fill in the required information:
   • Key: A unique identifier for the secret (e.g., API_KEY, DATABASE_PASSWORD)
   • Value: The sensitive data to store (e.g., the actual API key or password)
4. Click “Create” to save the vault entry

The value is automatically encrypted and stored securely in the database.

Vault Key Requirements

Vault keys must:

• Be unique within a project
• Contain only uppercase letters, numbers, and underscores
• Start with a letter
• Be between 1 and 255 characters
• Follow environment variable naming conventions for consistency

Example valid keys: API_KEY, DATABASE_URL, JWT_SECRET, STRIPE_API_KEY

Value Encryption

Vault values are encrypted using the configured encryption key. This means:

• Values are never stored in plain text
• Only authorized users with proper access can decrypt and view values
• The encryption key is managed by the system administrator
• Encryption is transparent to authorized users

Viewing Vault Entries

When viewing vault entries in the project vault page, you can:

1. See all vault entries in a list view with their keys
2. Toggle visibility of values (displayed as password fields by default)
3. Filter entries by key name using the search box
4. Use pagination to navigate through large numbers of entries

Value Security

By default, vault values are hidden and displayed as masked password fields. To view a value:

1. Click the “Show/Hide” button next to the vault entry
2. The value will be decrypted and displayed
3. Click the button again to hide the value

Updating Vault Values

To update an existing vault entry’s value:

1. Navigate to the project vault page
2. Click the “Edit” button (pencil icon) on the vault entry you want to modify
3. A modal will appear with the current value
4. Modify the value in the text field
5. Click “Update” to save the changes

Note that you can only update the value of an entry, not its key. If you need to change the key, you must delete the entry and create a new one.

Deleting Vault Entries

To delete a vault entry:

1. Navigate to the project vault page
2. Click the “Delete” button (trash icon) on the vault entry
3. Confirm the deletion in the modal that appears

⚠️ Warning: Deleting a vault entry permanently removes the stored secret. Make sure you have another copy or have already rotated the secret elsewhere before deleting it.

Filtering and Pagination

The vault page includes helpful filtering and navigation features:

Filtering Vault Entries

To find specific vault entries:

1. Use the search box labeled “Filter vaults…”
2. Type any part of the vault key name
3. The list automatically filters to show matching entries

Pagination

For projects with many vault entries:

1. Use the pagination controls to navigate between pages
2. The page displays up to 10 entries at a time by default
3. Click the page number buttons to jump to a specific page
4. Use arrow buttons to move sequentially through pages

User Permissions

Access to vault management is controlled by user roles and project membership:

Additionally, users can only access vaults for projects they are members of.

Vault Security Best Practices

For optimal vault security and management:

1. Descriptive Keys: Use clear, descriptive key names that indicate the secret’s purpose
2. Rotate Regularly: Periodically rotate sensitive values like API keys and passwords
3. Minimal Exposure: Only expose vault values to routes and services that absolutely need them
4. Access Control: Use project membership to limit who can view and manage vaults
5. Audit: Keep track of who accesses vault entries (if audit logging is available)
6. Naming Conventions: Follow environment variable naming conventions for consistency (UPPERCASE_WITH_UNDERSCORES)
7. No Plain Text: Never store plain text passwords or unencrypted secrets elsewhere
8. Secure Deletion: Delete vault entries when they are no longer needed
9. Version Control: Never commit secrets to version control; use vaults instead
10. Backup: Ensure sensitive credentials are properly backed up outside the vault system

Using Vault Values in Routes

While vault entries are managed through the web interface, they can be accessed programmatically within your routes:

1. Vault values are encrypted at rest but decrypted when accessed by authorized users
2. Routes can reference vault entries to retrieve sensitive configuration
3. Access is controlled by project membership and user role
4. All vault access is logged for security auditing

API Endpoints

Vault operations can also be performed via the APIs:

• Create: POST /vault/create - Create a new vault entry
• Fetch All: GET /vault/fetch - Retrieve all vault entries for a project
• Fetch One: GET /vault/fetch/one - Retrieve a specific vault entry
• Update: PATCH /vault/update - Update a vault entry’s value
• Delete: DELETE /vault/delete - Delete a vault entry

All vault API endpoints require:

• Valid JWT authentication (the authenticated user’s uid from the token)
• Project membership (user must be a member of the project)
• Appropriate user role (ADMIN or ROOT)

Related Documentation

• Projects - Project management and organization
• Collections - Data collection management
• Routes - Creating API endpoints that can use vault values