Skip to main content

Keys

Keys are individual environment variables stored in your key library. They're reusable across multiple bundles.

What is a Key?​

A key represents a single environment variable with:

  • Name - Variable name (e.g., DATABASE_URL, API_KEY, PORT)
  • Value - The secret or configuration value (encrypted at-rest)
  • Type - Secret (masked) or Non-secret (visible)
  • Description - Optional documentation

Key Benefits​

Reusability

  • Attach the same key to multiple bundles
  • Update once, propagates to all bundles

Organization

  • Central library for all environment variables
  • Search and filter by name or description

Security

  • Encrypted at-rest (AES-256-GCM)
  • Never stored in plaintext
  • Masked in UI by default

Creating Keys​

Method 1: Manual Entry​

Via Web UI:

  1. Go to https://env.cat/keys
  2. Click "+ Create Key"
  3. Fill in the form:
    • Name: DATABASE_URL
    • Value: postgres://user:pass@localhost:5432/db
    • Type: Secret (masked) or Non-secret
    • Description: "PostgreSQL connection string"
  4. Click "Create"

Via API:

curl -X POST https://env.cat/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DATABASE_URL",
    "value": "postgres://user:pass@localhost:5432/db",
    "is_secret": true,
    "description": "PostgreSQL connection string"
  }'

The vendor gallery provides pre-built key templates for popular services.

How it works:

  1. Go to https://env.cat/keys
  2. Click "Browse Vendor Gallery"
  3. Browse categories:
    • Databases (PostgreSQL, MySQL, MongoDB, Redis)
    • Payment (Stripe, PayPal)
    • AI/ML (OpenAI, Anthropic, Replicate)
    • Cloud (AWS, Azure, GCP)
    • Tools (Sentry, Datadog, SendGrid)
  4. Select a vendor (e.g., "PostgreSQL")
  5. Click "Add to Library"
  6. Fill in your actual values
  7. Click "Save"

Example: PostgreSQL Template

DATABASE_URL      - postgres://user:pass@host:5432/db
DATABASE_HOST     - localhost
DATABASE_PORT     - 5432
DATABASE_NAME     - myapp
DATABASE_USER     - postgres
DATABASE_PASSWORD - ••••••••

All fields are pre-configured with names and descriptions. You just fill in your values.

Method 3: Import from File​

From .env file:

  1. Go to https://env.cat/keys
  2. Click "Import" → "From .env"
  3. Paste or upload your .env file: 
    DATABASE_URL=postgres://user:pass@localhost:5432/db
    API_KEY=sk_live_abc123xyz
    PORT=3000
  4. Review keys (mark secrets)
  5. Click "Import"

From JSON:

[
  {
    "name": "DATABASE_URL",
    "value": "postgres://...",
    "is_secret": true
  },
  {
    "name": "PORT",
    "value": "3000",
    "is_secret": false
  }
]

Managing Keys​

View Key Details​

  1. Go to https://env.cat/keys
  2. Click on a key name
  3. See:
    • Current value (decrypted, visible only to you)
    • Which bundles use this key
    • Created/updated timestamps

Edit Key Value​

Important: Changes propagate to all bundles using this key.

  1. Go to key details page
  2. Click "Edit"
  3. Update value
  4. Click "Save"

All bundles using this key will immediately reflect the new value.

Delete Key​

Warning: This removes the key from all bundles.

  1. Go to key details page
  2. Click "Delete"
  3. Confirm deletion
  4. Key removed from library and all bundles

Search & Filter​

Search by name:

Search: "DATABASE"
Results: DATABASE_URL, DATABASE_HOST, DATABASE_PORT

Filter by bundle:

Filter: "Used in 'dev/api'"
Results: Only keys attached to dev/api bundle

Key Types​

Secret Keys​

Definition: Sensitive values that should never be exposed.

Examples:

  • API keys (STRIPE_SECRET_KEY)
  • Passwords (DATABASE_PASSWORD)
  • Access tokens (GITHUB_TOKEN)
  • Private keys (JWT_PRIVATE_KEY)

Behavior:

  • Masked in UI (••••••••)
  • Never logged
  • Encrypted at-rest and in-transit

Non-Secret Keys​

Definition: Configuration values safe to display.

Examples:

  • Port numbers (PORT=3000)
  • Feature flags (ENABLE_ANALYTICS=true)
  • Public URLs (PUBLIC_URL=https://example.com)
  • Environment names (NODE_ENV=production)

Behavior:

  • Visible in UI
  • Can be copied directly
  • Still encrypted at-rest (for consistency)

Best Practices​

Naming Conventions​

Use SCREAMING_SNAKE_CASE:

✅ DATABASE_URL
✅ STRIPE_SECRET_KEY
✅ MAX_CONNECTIONS

❌ databaseUrl
❌ stripe-secret-key
❌ maxConnections

Be descriptive:

✅ POSTGRES_PRIMARY_DATABASE_URL
✅ STRIPE_LIVE_SECRET_KEY
✅ REDIS_SESSION_CACHE_URL

❌ DB_URL
❌ KEY
❌ CACHE

Group related keys:

POSTGRES_HOST
POSTGRES_PORT
POSTGRES_DATABASE
POSTGRES_USER
POSTGRES_PASSWORD

Security​

Mark secrets correctly:

  • Use "Secret" type for sensitive values
  • Use "Non-secret" for safe configuration

Rotate secrets regularly:

  • Update key values periodically
  • Especially after team member departures

Avoid hardcoding:

  • Never commit keys to Git
  • Use env.cat instead of .env files in repos

Organization​

Use descriptions:

Name: STRIPE_SECRET_KEY
Description: "Production Stripe secret key (live mode)"

Document source:

Description: "From AWS Secrets Manager: prod/stripe/secret-key"

Track expiration:

Description: "Expires: 2025-12-31 (rotate before)"

Databases​

  • PostgreSQL - Connection strings, credentials
  • MySQL - Host, port, credentials
  • MongoDB - Connection URI, replica sets
  • Redis - Connection URL, auth
  • SQLite - File paths

Payment Processors​

  • Stripe - Publishable + secret keys (test/live)
  • PayPal - Client ID, secret
  • Square - Access tokens, application ID

AI/ML Services​

  • OpenAI - API keys, organization ID
  • Anthropic - API keys
  • Replicate - API tokens
  • Hugging Face - Access tokens

Cloud Providers​

  • AWS - Access key, secret key, region
  • Azure - Subscription ID, tenant ID, credentials
  • GCP - Service account JSON, project ID

Monitoring & Analytics​

  • Sentry - DSN, auth tokens
  • Datadog - API keys, app keys
  • New Relic - License keys

Communication​

  • SendGrid - API keys
  • Twilio - Account SID, auth token
  • Mailgun - API keys, domain

Advanced Features​

Key Propagation​

When you update a key value:

  1. Value updated in database (encrypted)
  2. All bundles using this key immediately reflect change
  3. Next CLI approval delivers new value
  4. No manual sync required

Example:

1. Update DATABASE_PASSWORD in key library
2. Key is used in bundles: dev/api, prod/api, staging/api
3. All three bundles now have the new password
4. Next time you run `envcat get`, you get the new password

Bulk Operations​

Coming soon:

  • Bulk import from multiple files
  • Bulk export to different formats
  • Bulk delete with confirmation
  • Bulk edit (find & replace)

Troubleshooting​

Can't Create Key​

Issue: "Key name already exists"

Solution:

  • Key names must be unique within your tenant
  • Use the existing key and attach it to your bundle
  • Or rename your new key (e.g., DATABASE_URL_V2)

Key Not Showing in Bundle​

Issue: Created key but can't see it in bundle

Solution:

  • Keys must be explicitly attached to bundles
  • Go to bundle page → "Attach Keys" → select your key
  • Or go to key page → "Add to Bundle" → select bundle

Lost Key Value​

Issue: Accidentally overwrote key value

Solution:

  • Key values are encrypted, not recoverable
  • Check your .env backups or secrets manager
  • Rotate the secret and update the key

Next Steps​

Now that you understand keys:

  1. Create Bundles - Organize keys into bundles
  2. Approval Flow - Learn how secrets are delivered
  3. Try It Out - Test the CLI approval flow
  4. CLI Reference - Install and use the CLI

Need Help?​