Last updated: March 15, 2026

To use Bitwarden custom fields, open any vault item, scroll to the “Custom Fields” section, and click “Add Item” to create Text (visible metadata), Hidden (masked values like API keys), or Protected (extra-secure, non-searchable) fields. Custom fields let you store API keys, database connection strings, SSH configurations, and environment tags alongside your login credentials, and you can retrieve them programmatically via the Bitwarden CLI with bw get item "name" | jq '.fields[]'.

What Are Custom Fields?

Custom fields are additional data points you can attach to any vault item in Bitwarden. Each field consists of a name and value, with optional attributes for masking (hiding the value) or marking the field as a protected note. This flexibility makes custom fields ideal for storing API keys, database credentials, server addresses, and other developer-specific information.

To access custom fields, open any vault item in the Bitwarden web vault, desktop app, or browser extension. Scroll past the standard login fields to find the “Custom Fields” section. Click “Add Item” to create your first custom field.

Prerequisites

Before you begin, make sure you have the following ready:

Step 1 - Field Types and Their Applications

Bitwarden supports three distinct field types, each serving different use cases:

Text Fields store plain text values. Use these for URLs, server hostnames, or any non-sensitive metadata you want to associate with an entry. Text fields appear as readable text in the vault.

Hidden Fields mask their values similar to password fields. These are appropriate for API keys, tokens, or any sensitive string you don’t want visible on screen. Hidden fields still copy to clipboard normally when you click them.

Protected Fields provide an additional security layer. The value remains hidden and requires explicit action to reveal. Protected fields cannot be searched or exported in plaintext, making them suitable for particularly sensitive data like recovery codes or encryption keys.

Practical Examples for Developers

Storing API Credentials

For services requiring API keys, create a dedicated login item with custom fields:

Service - GitHub
Username - dev@example.com
Password - [master password]

Custom Fields:
- API Key (Hidden): ghp_xxxxxxxxxxxxxxxxxxxx
- Organization (Text): my-company
- OAuth Secret (Protected): [sensitive value]

This organization keeps all authentication-related data in one place while clearly separating human credentials from machine credentials.

Database Connection Strings

Database credentials often require multiple pieces of information. Custom fields handle this elegantly:

Item - Production Database
Password - [database password]

Custom Fields:
- Host (Text): db.prod.example.com
- Port (Text): 5432
- Database (Text): main_app_production
- SSL Mode (Text): require
- Connection String (Text): postgresql://user@db.prod.example.com:5432/main_app_production

The connection string field aggregates the individual values into a format ready for direct use in configuration files or environment variables.

SSH Key Management

Managing SSH keys becomes simpler with custom fields:

Item - Production Server SSH
Password - [SSH key passphrase]

Custom Fields:
- Host (Text): production.example.com
- Port (Text): 22
- Private Key (Protected): [paste private key content]
- Public Key (Text): ssh-rsa AAAAB3NzaC1...
- Jump Host (Text): bastion.example.com

This approach keeps all SSH configuration details accessible alongside your credentials, eliminating the need to search through documentation or configuration files.

Step 2 - Automate with the Bitwarden CLI

The Bitwarden command-line interface (CLI) provides programmatic access to custom fields, enabling automation scripts and integration with development workflows.

Install the CLI using npm:

npm install -g @bitwarden/cli

Authenticate with your vault:

bw login your@email.com

Retrieve an item and extract custom field values using JSON parsing:

Get item with custom fields
bw get item "GitHub API" | jq '.fields[] | select(.name == "API Key") | .value'

This command returns the API key value directly, making it useful for shell scripts:

#!/bin/bash
API_KEY=$(bw get item "GitHub API" | jq -r '.fields[] | select(.name == "API Key") | .value')
curl -H "Authorization - token $API_KEY" https://api.github.com/user

The CLI also supports creating items with custom fields programmatically:

bw create item login '{
  "name": "New API Service",
  "login": {
    "username": "service-account",
    "password": "generated-password"
  },
  "fields": [
    {"name": "API Key", "value": "key-value", "type": 1},
    {"name": "Environment", "value": "production", "type": 0}
  ]
}'

Field type 0 represents text, while 1 represents hidden fields.

Step 3 - Organizing Large Vaults

Custom fields shine when organizing vault entries for large projects or multiple environments. Create consistent field naming conventions across items:

Use a text field named “Environment” with values like “production”, “staging”, or “development” on every credential item as an environment tag. Add a “Project” text field to group related credentials across different services.

For expiration tracking, store expiration dates in an “Expires” text field. Write a script using the CLI to check for upcoming expirations:

bw list items | jq -r '.[] | select(.fields != null) | select(.fields[] | .name == "Expires") | "\(.name): \((.fields[] | select(.name == "Expires") | .value))"'

Security Considerations

While custom fields enhance organization, follow security best practices:

Never store plaintext passwords in text fields, use hidden or protected fields instead. Be cautious with clipboard operations; clear clipboard data after copying sensitive values. The Bitwarden CLI supports automatic clipboard clearing with the --clipboard flag and --timeout parameter.

When sharing items through Bitwarden Send or organizational sharing, custom field visibility depends on the item’s sharing settings. Review shared items carefully to ensure sensitive fields aren’t exposed unintentionally.

Advanced Field Patterns for Power Users

Multi-Step Deployment Documentation

Store complete deployment instructions in custom fields:

Item - Production Deployment Instructions
Password - [deploy user password]

Custom Fields:
- Deployment Script URL (Text): https://deploy.example.com/scripts/prod-deploy.sh
- Required Environment Variables (Protected): [entire .env file content]
- Pre-deployment Checklist (Text): [step-by-step checklist]
- Rollback Command (Protected): git reset --hard [commit-hash]; ./deploy.sh
- Notification Channel (Text): #production-deployments-slack

This approach keeps deployment knowledge with credentials, preventing situations where credentials exist but the deployment process is lost to departing team members.

Credential Expiration Tracking

Implement automated expiration monitoring:

#!/bin/bash
Check expiring credentials in Bitwarden
bw list items | jq -r '.[] | select(.fields != null) |
  select(.fields[] | select(.name == "Expires") |
  ((.value | split("-")[0] | tonumber) - 2026 < 1)) |
  "\(.name): Expires \((.fields[] | select(.name == "Expires") | .value))"'

Geographic/Temporal Field Organization

Add custom fields for context-aware credential use:

Item - Production Database - US Region
Password - [db password]

Custom Fields:
- Region (Text): us-east-1
- Availability Zone (Text): us-east-1a
- Timezone (Text): America/New_York
- Business Hours Only (Text): 6am-8pm EST Monday-Friday
- Backup Window (Text): Sunday 2am-4am EST

This allows scripts to select credentials based on deployment context.

Step 4 - Integration with Infrastructure-as-Code

Connect Bitwarden credentials to Terraform or other IaC tools:

#!/bin/bash
Terraform variable file generator from Bitwarden

bw unlock your@email.com  # Or use BW_SESSION environment variable

cat > terraform.tfvars <<'EOF'
Auto-generated from Bitwarden - DO NOT EDIT MANUALLY

Database credentials
rds_password = "$(bw get item 'RDS Production' | jq -r '.login.password')"
db_host = "$(bw get item 'RDS Production' | jq -r '.fields[] | select(.name=="Host") | .value')"

API keys
stripe_api_key = "$(bw get item 'Stripe Live' | jq -r '.fields[] | select(.name=="API Key") | .value')"

AWS credentials
aws_access_key = "$(bw get item 'AWS Prod' | jq -r '.login.username')"
aws_secret_key = "$(bw get item 'AWS Prod' | jq -r '.login.password')"
EOF

Then provision with Terraform
terraform apply -var-file=terraform.tfvars

Threat Modeling Custom Fields

Understand the security properties of different field types:

Text Fields - Visible in plaintext. Use only for non-sensitive metadata like server hostnames or documentation URLs.

Hidden Fields - Masked in UI but still searchable and exportable. Suitable for API keys that don’t require extra protection layers.

Protected Fields - Completely hidden, non-searchable, not included in plaintext exports. Best for recovery codes, encryption keys, or emergency credentials.

Export shows protected fields as empty
bw export --format json | jq '.items[].fields[] | select(.type == 2) | .value'

Output - null (protected fields are not exported unencrypted)

Use Protected fields for anything you absolutely don’t want leaving your Bitwarden vault, even in encrypted exports.

Step 5 - Field Naming Conventions at Scale

Establish consistent field naming to support large vaults:

Prefixed naming:
- API_KEY (text field)
- API_ENDPOINT (text field)
- API_RATE_LIMIT (text field)
- CRED_USERNAME (hidden field)
- CRED_PASSWORD (hidden field)
- SEC_RECOVERY_CODE (protected field)

This allows consistent grep patterns and CLI queries:

Find all API endpoints
bw list items | jq '.[] | .fields[] | select(.name | startswith("API_")) | .name'

Extract specific configuration
bw get item "MyService" | jq '.fields[] | select(.name | startswith("API_")) | {name, value}'

Audit and Compliance

Track credential usage for compliance:

{
  "field": "ServiceAccountKey",
  "purpose": "Production deployment automation",
  "rotated": "2026-03-01",
  "next_rotation": "2026-06-01",
  "accessed_by": ["deploy-bot", "senior-devops"],
  "compliance": ["SOC2", "ISO27001"]
}

Document this in custom fields for regulatory audits.

Troubleshooting

Configuration changes not taking effect

Restart the relevant service or application after making changes. Some settings require a full system reboot. Verify the configuration file path is correct and the syntax is valid.

Permission denied errors

Run the command with sudo for system-level operations, or check that your user account has the necessary permissions. On macOS, you may need to grant terminal access in System Settings > Privacy & Security.

Connection or network-related failures

Check your internet connection and firewall settings. If using a VPN, try disconnecting temporarily to isolate the issue. Verify that the target server or service is accessible from your network.

Frequently Asked Questions

How long does it take to complete this setup?

For a straightforward setup, expect 30 minutes to 2 hours depending on your familiarity with the tools involved. Complex configurations with custom requirements may take longer. Having your credentials and environment ready before starting saves significant time.

What are the most common mistakes to avoid?

The most frequent issues are skipping prerequisite steps, using outdated package versions, and not reading error messages carefully. Follow the steps in order, verify each one works before moving on, and check the official documentation if something behaves unexpectedly.

Do I need prior experience to follow this guide?

Basic familiarity with the relevant tools and command line is helpful but not strictly required. Each step is explained with context. If you get stuck, the official documentation for each tool covers fundamentals that may fill in knowledge gaps.

Is this approach secure enough for production?

The patterns shown here follow standard practices, but production deployments need additional hardening. Add rate limiting, input validation, proper secret management, and monitoring before going live. Consider a security review if your application handles sensitive user data.

Where can I get help if I run into issues?

Start with the official documentation for each tool mentioned. Stack Overflow and GitHub Issues are good next steps for specific error messages. Community forums and Discord servers for the relevant tools often have active members who can help with setup problems.

Related Articles

Built by theluckystrike. More at zovo.one