# KeyEnv Documentation
> KeyEnv is a secrets management platform for developer teams. It provides encrypted storage, syncing, and injection of environment variables across projects, environments, and CI/CD pipelines.
KeyEnv includes a CLI, web dashboard, REST API, and SDKs for 10+ languages. Secrets are encrypted at rest with AES-256-GCM, versioned with full audit trails, and scoped by environment-level permissions (none/read/write/admin).
Every documentation page is also available as raw markdown by appending `.md` to its URL, for example `https://keyenv.dev/docs/cli.md`. The OpenAPI specification is published at `/openapi.yaml` and `/openapi.json`.
This file contains the complete KeyEnv documentation as a single markdown document.
---
# Documentation
## KeyEnv Documentation
Learn how to use KeyEnv to manage secrets across your development workflow.
Source: https://keyenv.dev/docs/
KeyEnv is a secure secrets management platform that helps teams sync environment variables across development, staging, and production environments.
### Quick Links
- [Quick Start](/docs/getting-started): Get up and running in 5 minutes
- [CLI Reference](/docs/cli): Complete command documentation
- [Web App Guide](/docs/web-app): Manage secrets in the browser
- [Secret Rotation](/docs/web-app/rotations): Auto-rotate database credentials
- [SDKs & Integrations](/docs/sdks): Node.js, Python SDKs & GitHub Action
### Why KeyEnv?
- **Secure by default** - Secrets are encrypted at rest and in transit
- **Database credential rotation** - Automatically rotate PostgreSQL and MySQL passwords
- **Version history** - Track every change with full audit logs
- **Team collaboration** - Share secrets securely with your team
- **CLI-first workflow** - Sync secrets with a single command
### Getting Started
Install the CLI and sync your first secrets:
```bash
# Install via Homebrew
brew install keyenv
# Login to your account
keyenv login
# Initialize a project
keyenv init
# Pull secrets to .env
keyenv pull
```
Ready to dive in? Start with our [Quick Start Guide](/docs/getting-started).
---
# Getting Started
## Getting Started
Get up and running with KeyEnv in minutes.
Source: https://keyenv.dev/docs/getting-started/
This guide will help you set up KeyEnv and sync your first secrets.
### Prerequisites
- A KeyEnv account ([sign up here](https://app.keyenv.dev/signup))
- Node.js 18+ or any modern development environment
### Steps
1. [Install the CLI](/docs/getting-started/installation)
2. [Create your first project](/docs/getting-started/first-project)
3. [Understand core concepts](/docs/getting-started/concepts)
Ready? Let's [install the CLI](/docs/getting-started/installation).
## Installation
Install the KeyEnv CLI on your machine.
Source: https://keyenv.dev/docs/getting-started/installation/
The KeyEnv CLI is available for macOS, Linux, and Windows.
### Quick Install (Recommended)
Install KeyEnv with a single command:
```bash
curl -fsSL https://keyenv.dev/install.sh | bash
```
This script automatically detects your operating system and architecture, downloads the correct binary, and installs it to `~/.keyenv/bin`.
#### Install a Specific Version
```bash
curl -fsSL https://keyenv.dev/install.sh | bash -s -- v0.1.0
```
#### Custom Install Location
```bash
KEYENV_INSTALL_DIR=/usr/local/bin curl -fsSL https://keyenv.dev/install.sh | bash
```
After installation, add KeyEnv to your PATH if prompted:
```bash
export PATH="$HOME/.keyenv/bin:$PATH"
```
Add this line to your `~/.bashrc`, `~/.zshrc`, or shell profile to make it permanent.
---
### Alternative Installation Methods
#### Binary Download
Download pre-built binaries from [GitHub Releases](https://github.com/keyenv/keyenv/releases).
**macOS (Apple Silicon):**
```bash
curl -L https://github.com/keyenv/keyenv/releases/latest/download/keyenv-aarch64-apple-darwin.tar.gz | tar xz
sudo mv keyenv /usr/local/bin/
```
**macOS (Intel):**
```bash
curl -L https://github.com/keyenv/keyenv/releases/latest/download/keyenv-x86_64-apple-darwin.tar.gz | tar xz
sudo mv keyenv /usr/local/bin/
```
**Linux (x64):**
```bash
curl -L https://github.com/keyenv/keyenv/releases/latest/download/keyenv-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv keyenv /usr/local/bin/
```
**Linux (ARM64):**
```bash
curl -L https://github.com/keyenv/keyenv/releases/latest/download/keyenv-aarch64-unknown-linux-gnu.tar.gz | tar xz
sudo mv keyenv /usr/local/bin/
```
#### Windows
Download `keyenv-x86_64-pc-windows-msvc.zip` from [GitHub Releases](https://github.com/keyenv/keyenv/releases), extract it, and add the folder to your PATH.
#### Build from Source
Requires Rust 1.70+:
```bash
git clone https://github.com/keyenv/keyenv.git
cd keyenv/cli
cargo build --release
```
The binary will be at `target/release/keyenv`.
---
### Verify Installation
```bash
keyenv --version
```
You should see output like:
```
keyenv 0.1.0
```
### Troubleshooting
#### "command not found" after installation
Make sure `~/.keyenv/bin` is in your PATH:
```bash
echo $PATH | grep -q ".keyenv" && echo "PATH is set" || echo "PATH not set"
```
Add to your shell profile:
```bash
echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
#### Permission denied
If using `/usr/local/bin`, you may need sudo:
```bash
sudo mv keyenv /usr/local/bin/
```
Or use the default install location (`~/.keyenv/bin`) which doesn't require sudo.
### Next Steps
Now that you have the CLI installed, [create your first project](/docs/getting-started/first-project).
## Your First Project
Create a KeyEnv project and sync your first secrets in under 5 minutes.
Source: https://keyenv.dev/docs/getting-started/first-project/
This tutorial walks you through the complete KeyEnv workflow: authenticating, creating a project, managing secrets, and running your application with secrets injected.
**Prerequisites:**
- [KeyEnv CLI installed](/docs/getting-started/installation)
- A KeyEnv account ([sign up here](https://app.keyenv.dev/signup))
---
### Step 1: Login
Authenticate with your KeyEnv account:
```bash
keyenv login
```
This opens your browser for authentication. Once complete, you'll see:
```
✓ Logged in as you@example.com
✓ Access token saved to keychain
```
Verify your session anytime with:
```bash
keyenv whoami
```
---
### Step 2: Initialize a Project
Navigate to your project directory:
```bash
cd ~/my-project
keyenv init
```
You'll be prompted to either select an existing project or create a new one:
```
? Select a project:
❯ Create new project
my-existing-project
another-project
```
If creating new, enter a project name:
```
? Project name: my-awesome-app
? Default environment: development
✓ Project 'my-awesome-app' created
✓ Configuration saved to .keyenv.toml
```
This creates a `.keyenv.toml` configuration file:
```toml
project_id = "abc123-def456-..."
default_environment = "development"
```
> **Note**
>
> The `.keyenv.toml` file is safe to commit. It only contains the project ID, not secrets.
---
### Step 3: Add Your First Secrets
Add secrets using the CLI:
```bash
# Set a simple secret
keyenv set DATABASE_URL "postgres://localhost:5432/mydb"
# Set multiple secrets
keyenv set API_KEY "your-api-key"
keyenv set JWT_SECRET "your-jwt-secret"
```
For sensitive values, pipe from stdin to avoid shell history:
```bash
echo "sk_live_abc123..." | keyenv set STRIPE_SECRET_KEY -
```
List your secrets to verify:
```bash
keyenv list
```
Output:
```
Environment: development
DATABASE_URL postgres://localhost:5432/mydb
API_KEY your-*****-key
JWT_SECRET ********
STRIPE_SECRET_KEY sk_live_*****
```
---
### Step 4: Pull Secrets to .env
Sync secrets to a local `.env` file:
```bash
keyenv pull
```
Output:
```
✓ Pulled 4 secrets to .env
```
Your `.env` file now contains:
```
DATABASE_URL=postgres://localhost:5432/mydb
API_KEY=your-api-key
JWT_SECRET=your-jwt-secret
STRIPE_SECRET_KEY=sk_live_abc123...
```
> **Warning**
>
> Add `.env` to your `.gitignore` to prevent accidentally committing secrets.
---
### Step 5: Run with Secrets Injected
The recommended way to use secrets is with `keyenv run`. This injects secrets as environment variables without writing them to disk:
```bash
keyenv run -- npm start
```
Or with any command:
```bash
# Node.js
keyenv run -- node server.js
# Python
keyenv run -- python app.py
# Docker
keyenv run -- docker-compose up
```
The `--` separates KeyEnv options from your command.
---
### Step 6: Work with Different Environments
KeyEnv supports multiple environments (development, staging, production). Specify the environment using the `-e/--env` flag:
```bash
# Pull staging secrets
keyenv pull --env staging
# Run with production secrets
keyenv run --env production -- npm start
# Set a default environment in .keyenv.toml
# Edit the file and change: default_environment = "staging"
```
> **Note**
>
> The `-e/--env` flag works with most commands (`pull`, `push`, `run`, `set`, `get`, `list`). To change your default environment, edit the `default_environment` value in your `.keyenv.toml` file.
---
### What's Next?
You've learned the basics! Here's where to go next:
- **[Core Concepts](/docs/getting-started/concepts)** - Understand projects, environments, and teams
- **[CLI Reference](/docs/cli)** - Complete command documentation
- **[CI/CD Integration](/docs/guides/ci-cd)** - Set up secrets in your pipeline
- **[Docker Guide](/docs/guides/docker)** - Use KeyEnv with containers
---
### Quick Reference
| Command | Description |
|---------|-------------|
| `keyenv login` | Authenticate with KeyEnv |
| `keyenv init` | Initialize a project |
| `keyenv set KEY value` | Set a secret |
| `keyenv get KEY` | Get a secret value |
| `keyenv list` | List all secrets |
| `keyenv pull` | Sync secrets to .env |
| `keyenv run -- cmd` | Run command with secrets |
| `keyenv push` | Push local .env to server |
## Core Concepts
Understand the key concepts behind KeyEnv.
Source: https://keyenv.dev/docs/getting-started/concepts/
Understanding these concepts will help you get the most out of KeyEnv.
### Projects
A **project** is a collection of secrets for a single application or service. Each project can have multiple environments.
- Projects are identified by a unique ID
- You can switch between projects with `keyenv switch`
- Projects can be shared with team members
### Environments
**Environments** are isolated sets of secrets within a project. Common environments include:
| Environment | Purpose |
|-------------|---------|
| `development` | Local development |
| `staging` | Pre-production testing |
| `production` | Live application |
Each environment has its own set of secrets with the same keys but different values:
```
# development
DATABASE_URL=postgres://localhost/mydb
# production
DATABASE_URL=postgres://prod-server/mydb
```
### Secrets
A **secret** is a key-value pair. Secrets have:
- **Key**: The environment variable name (e.g., `DATABASE_URL`)
- **Value**: The sensitive data
- **Version**: Incremented on each update
- **Description**: Optional documentation
### Version History
Every change to a secret is tracked. You can:
- View the history of changes with `keyenv history SECRET_NAME`
- See who made each change and when
- Audit access and modifications
### Environment Permissions
**Environment permissions** control who can access secrets in each environment. Permission levels:
| Role | Description |
|------|-------------|
| `none` | No access |
| `read` | View secrets only |
| `write` | View and modify secrets |
| `admin` | Full access + manage permissions |
This allows you to:
- Give developers full access to `development`
- Restrict `production` to senior engineers
- Grant read-only access for debugging
> **Note**
>
> Team admins automatically have full access to all environments.
### Service Tokens
**Service tokens** are API keys for CI/CD and automated systems. They:
- Have limited permissions (specific project/environment)
- Can be scoped to a single environment for extra security
- Never expire but can be revoked
- Are used instead of user authentication in automated pipelines
```bash
# In CI/CD, set the token as an environment variable
export KEYENV_TOKEN="env_..."
keyenv pull
```
### Team Collaboration
KeyEnv supports team workflows:
- **Members** can view and modify secrets
- **Admins** can manage team settings and members
- All changes are attributed to the user who made them
### Next Steps
Now that you understand the concepts, explore:
- [CLI commands](/docs/cli) for all operations
- [Web app guide](/docs/web-app) for browser-based management
## FAQ
Frequently asked questions about KeyEnv.
Source: https://keyenv.dev/docs/getting-started/faq/
### General
#### What is KeyEnv?
KeyEnv is a secrets management platform that helps teams securely store, sync, and share environment variables across development workflows. It replaces insecure practices like sharing `.env` files via Slack or email.
#### How is KeyEnv different from .env files?
| Aspect | .env Files | KeyEnv |
|--------|-----------|--------|
| Security | Unencrypted, often committed to git | Encrypted at rest, never in git |
| Sharing | Copy/paste, email, Slack | Secure team access with roles |
| Sync | Manual | Automatic with CLI |
| Audit | None | Full audit trail |
| Environments | Manual management | Built-in dev/staging/prod |
#### Is KeyEnv free?
Yes! The Free plan includes:
- 3 projects
- 100 secrets per environment
- 1 team member
- All core features
See our [pricing page](/pricing) for plan details.
### Security
#### How are secrets encrypted?
Secrets are encrypted using AES-256-GCM before storage. Each secret has a unique initialization vector (IV). The encryption key is securely managed and never exposed.
#### Can KeyEnv employees see my secrets?
No. Secrets are encrypted at rest with keys that KeyEnv employees cannot access. We follow zero-knowledge principles for secret storage.
#### Is KeyEnv SOC 2 compliant?
We are working towards SOC 2 Type II compliance. Contact us for our current security documentation.
#### What happens if KeyEnv is down?
The CLI caches secrets locally (encrypted) so your applications continue working. Once connectivity is restored, secrets sync automatically.
### CLI
#### How do I install the CLI?
```bash
curl -fsSL https://keyenv.dev/install.sh | bash
```
See the [installation guide](/docs/getting-started/installation) for more options.
#### The CLI says "not authenticated"
Run `keyenv login` to authenticate. If you're in a CI/CD environment, set the `KEYENV_TOKEN` environment variable with a service token.
#### How do I switch environments?
```bash
# Pull secrets from staging
keyenv pull -e staging
# Run command with production secrets
keyenv run -e production -- npm start
```
#### Can I use KeyEnv offline?
Yes, once you've pulled secrets, they're cached locally. You can work offline and sync when back online.
### Teams & Collaboration
#### How do I invite team members?
1. Go to your project's **Team** page
2. Click **Invite Member**
3. Enter their email and select a role
4. They'll receive an invitation email
#### What are the different roles?
| Role | Can View Secrets | Can Edit Secrets | Can Manage Team |
|------|-----------------|------------------|-----------------|
| Member | Yes | Yes | No |
| Admin | Yes | Yes | Yes |
#### Can I have different access per environment?
Yes! You can set per-environment permissions (admin, write, read, or none) for each team member. Go to **Project Settings > Permissions** to configure environment-level access.
### CI/CD & Automation
#### How do I use KeyEnv in GitHub Actions?
```yaml
steps:
- name: Install KeyEnv
run: curl -fsSL https://keyenv.dev/install.sh | bash
- name: Pull secrets
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
run: keyenv pull -e production
```
See the [CI/CD guide](/docs/guides/ci-cd) for more examples.
#### Should I use a service token or my personal login?
Always use service tokens for automation:
- **Service tokens**: For CI/CD, scripts, automated processes
- **Personal login**: For local development only
#### How do I rotate a service token?
1. Create a new service token
2. Update your CI/CD secrets with the new token
3. Verify the new token works
4. Revoke the old token
### Billing & Plans
#### How do I upgrade my plan?
Go to **Settings** → **Billing** and click **Upgrade**. You'll be redirected to our secure checkout.
#### Can I cancel anytime?
Yes. Cancel from the billing page. You'll retain access until the end of your billing period.
#### Do you offer annual billing?
Annual billing with discounts is coming soon. Contact us for early access.
### Troubleshooting
#### "Project not found" error
- Verify you're in the correct directory (check for `.keyenv.toml`)
- Run `keyenv init` if you haven't set up the project
- Check that you have access to the project
#### "Permission denied" error
- Verify your role has the required permissions
- For service tokens, check the token has access to the environment
- Try logging out and back in: `keyenv logout && keyenv login`
#### Secrets not updating
```bash
# Force a fresh pull
keyenv pull --force
# List current secrets to verify
keyenv list
```
#### Need more help?
- Email: support@keyenv.dev
- Documentation: [keyenv.dev/docs](/docs)
---
# CLI Reference
## CLI Reference
Complete reference for all KeyEnv CLI commands.
Source: https://keyenv.dev/docs/cli/
The KeyEnv CLI provides commands for managing secrets from your terminal.
### Global Options
These options work with all commands:
| Option | Description |
|--------|-------------|
| --json | Output JSON instead of human-readable text |
| -q, --quiet | Minimize output (only essential info) |
| --no-color | Disable colored output |
| -v, --verbose | Enable verbose output |
| -h, --help | Print help information |
| -V, --version | Print version |
### Command Categories
#### Authentication
- [`login`](/docs/cli/authentication#login) - Authenticate with KeyEnv
- [`logout`](/docs/cli/authentication#logout) - Clear stored credentials
- [`whoami`](/docs/cli/authentication#whoami) - Display current user
#### Projects
- [`init`](/docs/cli/projects#init) - Initialize a project
- [`projects`](/docs/cli/projects#projects) - List all projects
- [`switch`](/docs/cli/projects#switch) - Switch to a different project
#### Secrets
- [`pull`](/docs/cli/secrets#pull) - Pull secrets from server
- [`push`](/docs/cli/secrets#push) - Push secrets to server
- [`list`](/docs/cli/secrets#list) - List all secrets
- [`get`](/docs/cli/secrets#get) - Get a secret value
- [`set`](/docs/cli/secrets#set) - Set a secret value
- [`delete`](/docs/cli/secrets#delete) - Delete a secret
- [`export`](/docs/cli/reference#export) - Export secrets to various formats
#### Workflow
- [`run`](/docs/cli/workflow#run) - Run command with secrets
- [`diff`](/docs/cli/workflow#diff) - Compare local and remote secrets
- [`history`](/docs/cli/workflow#history) - View secret history
#### Security
- [`scan`](/docs/cli/reference#security) - Scan for hardcoded secrets in your codebase
#### Tokens
- [`tokens list`](/docs/cli/reference#tokens) - List all service tokens
- [`tokens create`](/docs/cli/reference#tokens) - Create a new service token
- [`tokens revoke`](/docs/cli/reference#tokens) - Revoke a service token
- [`tokens rotate`](/docs/cli/reference#tokens) - Rotate a service token
#### Teams
- [`team list`](/docs/cli/reference#teams) - List your teams
- [`team show`](/docs/cli/reference#teams) - Show team details and members
- [`team invite`](/docs/cli/reference#teams) - Invite a member to a team
- [`team role`](/docs/cli/reference#teams) - Update a member's role
- [`team remove`](/docs/cli/reference#teams) - Remove a member from a team
#### Rotations
- [`rotations`](/docs/cli/reference#rotations) - Manage secret rotation configurations
#### Update
- [`update check`](/docs/cli/reference#update) - Check for CLI updates
- [`update install`](/docs/cli/reference#update) - Install the latest CLI version
#### Utility
- [`completions`](/docs/cli/reference#shell-completions) - Generate shell completion scripts
See the [full reference](/docs/cli/reference) for all commands on a single page.
## Authentication Commands
CLI commands for authentication and user management.
Source: https://keyenv.dev/docs/cli/authentication/
Commands for managing your KeyEnv authentication.
### login
Authenticate with the KeyEnv server.
```bash
keyenv login [OPTIONS]
```
#### Options
| Option | Description |
|--------|-------------|
| -t, --token <TOKEN> | Use a service token instead of browser auth |
| -s, --server <URL> | Specify a custom server URL |
#### Examples
```bash
# Interactive browser authentication
keyenv login
# Login with a service token (for CI/CD)
keyenv login --token env_abc123...
# Login to a self-hosted server
keyenv login --server https://keyenv.mycompany.com
```
#### Notes
- Browser authentication opens your default browser
- Tokens are stored securely in your system keychain (macOS/Windows) or encrypted file (Linux)
- Service tokens are typically used in CI/CD environments
---
### logout
Log out and clear stored credentials.
```bash
keyenv logout
```
#### Examples
```bash
keyenv logout
# ✓ Logged out successfully
```
#### Notes
- Removes the token from your keychain/credential store
- You'll need to run `keyenv login` again to use the CLI
---
### whoami
Display the currently authenticated user.
```bash
keyenv whoami
```
#### Examples
```bash
keyenv whoami
# User: you@example.com
# Server: https://api.keyenv.dev
# Current Project: my-project
```
#### JSON Output
```bash
keyenv whoami --json
```
```json
{
"id": "user_abc123",
"email": "you@example.com",
"name": "Your Name",
"server": "https://api.keyenv.dev",
"current_project": "my-project"
}
```
## Project Commands
CLI commands for managing KeyEnv projects.
Source: https://keyenv.dev/docs/cli/projects/
Commands for initializing and managing KeyEnv projects.
### init
Initialize a new KeyEnv project in the current directory.
```bash
keyenv init [OPTIONS]
```
#### Options
| Option | Description |
|--------|-------------|
| -n, --name <NAME> | Create a new project with this name |
| -p, --project <ID> | Link to an existing project by ID |
#### Examples
```bash
# Interactive initialization
keyenv init
# Create a new project
keyenv init --name "my-api"
# Link to existing project
keyenv init --project abc123-def456-...
```
#### What It Does
1. Prompts you to select or create a project
2. Creates a `.keyenv.toml` file with project configuration
3. Sets the default environment (usually `development`)
#### Configuration File
```toml
# .keyenv.toml
project_id = "abc123-def456-..."
default_environment = "development"
```
---
### projects
Manage KeyEnv projects. Requires a subcommand.
```bash
keyenv projects
```
#### Subcommands
| Command | Description |
|---------|-------------|
| list | List all available projects |
| show <id> | Show details for a specific project |
---
### projects list
List all available projects.
```bash
keyenv projects list
```
#### Examples
```bash
keyenv projects list
# Projects:
# • my-api (abc123...) ← current
# • frontend (def456...)
# • shared-services (ghi789...)
```
#### JSON Output
```bash
keyenv projects list --json
```
```json
{
"projects": [
{
"id": "abc123-...",
"name": "my-api",
"current": true
},
{
"id": "def456-...",
"name": "frontend"
}
],
"current_project": "abc123-..."
}
```
---
### projects show
Show details for a specific project.
```bash
keyenv projects show
```
#### Arguments
| Argument | Description |
|----------|-------------|
| ID | The project ID to show details for |
#### Examples
```bash
keyenv projects show abc123-def456-...
# Project: my-api
# ID: abc123-def456-...
# Environments: development, staging, production
# Created: 2024-01-15
```
#### JSON Output
```bash
keyenv projects show abc123-def456-... --json
```
```json
{
"id": "abc123-def456-...",
"name": "my-api",
"environments": ["development", "staging", "production"],
"created_at": "2024-01-15T10:30:00Z"
}
```
---
### switch
Switch to a different project.
```bash
keyenv switch
```
#### Arguments
| Argument | Description |
|----------|-------------|
| PROJECT | Project name or ID to switch to |
#### Examples
```bash
# Switch by name
keyenv switch frontend
# Switch by ID
keyenv switch def456-...
```
#### Notes
- Updates your global config to use the selected project
- Affects all subsequent commands in any directory
- Use `keyenv init` in a project directory for per-directory configuration
## Secret Commands
CLI commands for managing secrets.
Source: https://keyenv.dev/docs/cli/secrets/
Commands for managing secrets within a project.
### pull
Pull secrets from the server to a local `.env` file.
```bash
keyenv pull [OPTIONS]
```
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment to pull from (default: development) |
| -f, --force | Overwrite existing file without confirmation |
#### Examples
```bash
# Pull development secrets to .env
keyenv pull
# Pull production secrets to .env
keyenv pull -e production
# Pull staging secrets, overwrite existing
keyenv pull -e staging --force
```
---
### push
Push local secrets from a `.env` file to the server.
```bash
keyenv push [OPTIONS]
```
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment to push to (default: development) |
| -f, --force | Overwrite existing secrets |
#### Examples
```bash
# Push .env to development
keyenv push
# Force overwrite existing secrets
keyenv push --force
```
#### Behavior
Without `--force`:
- New secrets are created
- Existing secrets are skipped
- You'll see a summary: "Created: 5, Skipped: 3"
With `--force`:
- New secrets are created
- Existing secrets are updated
- You'll see: "Created: 2, Updated: 6"
---
### list
List all secrets in the current project (keys only, values hidden).
```bash
keyenv list [OPTIONS]
```
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment (default: development) |
#### Examples
```bash
keyenv list
# Secrets (development):
# • DATABASE_URL (v3)
# • STRIPE_KEY (v1)
# • API_SECRET (v2)
#
# 3 secrets
```
#### JSON Output
```bash
keyenv list --json
```
```json
{
"environment": "development",
"secrets": [
{ "key": "DATABASE_URL", "version": 3 },
{ "key": "STRIPE_KEY", "version": 1 }
],
"count": 2
}
```
---
### get
Get a specific secret value.
```bash
keyenv get [OPTIONS]
```
#### Arguments
| Argument | Description |
|----------|-------------|
| KEY | The secret key to retrieve |
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment (default: development) |
#### Examples
```bash
# Get a secret value
keyenv get DATABASE_URL
# Get from production
keyenv get DATABASE_URL -e production
# Use in scripts
export DB=$(keyenv get DATABASE_URL -q)
```
---
### set
Set a secret value (creates or updates).
```bash
keyenv set [OPTIONS]
```
#### Arguments
| Argument | Description |
|----------|-------------|
| KEY | The secret key |
| VALUE | The secret value (use - to read from stdin) |
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment (default: development) |
| -g, --generate <TYPE> | Generate a random secret value (type: password, uuid, hex, base64, alphanumeric) |
| -l, --length <N> | Length of generated secret in characters (default: 32, requires --generate) |
#### Examples
```bash
# Set a secret
keyenv set DATABASE_URL "postgres://localhost/mydb"
# Set in production
keyenv set API_KEY "sk_live_..." -e production
# Read from stdin (for sensitive values)
echo "super-secret" | keyenv set MY_SECRET -
# Pipe from a command
op read "op://vault/item/password" | keyenv set PASSWORD -
# Generate a random password
keyenv set API_SECRET --generate password
# Generate a UUID
keyenv set REQUEST_ID --generate uuid
# Generate a 64-character hex secret
keyenv set ENCRYPTION_KEY --generate hex --length 64
```
---
### delete
Delete a secret.
```bash
keyenv delete [OPTIONS]
```
#### Arguments
| Argument | Description |
|----------|-------------|
| KEY | The secret key to delete |
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment (default: development) |
| -y, --yes | Skip confirmation prompt |
#### Examples
```bash
# Delete with confirmation
keyenv delete OLD_API_KEY
# Delete without confirmation
keyenv delete OLD_API_KEY --yes
# Delete from production
keyenv delete DEPRECATED_KEY -e production -y
```
> **Warning**
>
> Deletion is permanent. Consider using version history before deleting if you might need the value later.
## Workflow Commands
CLI commands for development workflow.
Source: https://keyenv.dev/docs/cli/workflow/
Commands that integrate with your development workflow.
### run
Run a command with secrets injected as environment variables.
```bash
keyenv run [OPTIONS] --
```
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment (default: development) |
#### Examples
```bash
# Run npm start with secrets
keyenv run -- npm start
# Run with production secrets
keyenv run -e production -- node server.js
# Run any command
keyenv run -- python manage.py runserver
# Complex commands (use quotes)
keyenv run -- sh -c "echo $DATABASE_URL && npm test"
```
#### How It Works
1. Fetches secrets from the server
2. Injects them as environment variables
3. Runs your command with those variables
4. Secrets are never written to disk
> **Note**
>
> Use `keyenv run` when you want secrets available but don't want a `.env` file on disk.
---
### diff
Show differences between local `.env` file and remote secrets.
```bash
keyenv diff [OPTIONS]
```
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment (default: development) |
#### Examples
```bash
keyenv diff
# Comparing .env with development:
# + NEW_LOCAL_KEY (local only)
# - REMOVED_KEY (remote only)
# ~ CHANGED_KEY (modified)
#
# + local only - remote only ~ modified
```
#### Output
| Symbol | Meaning |
|--------|---------|
| + | Key exists locally but not on server |
| - | Key exists on server but not locally |
| ~ | Key exists in both but values differ |
#### JSON Output
```bash
keyenv diff --json
```
```json
{
"environment": "development",
"has_differences": true,
"differences": [
{ "key": "NEW_LOCAL_KEY", "status": "local_only" },
{ "key": "REMOVED_KEY", "status": "remote_only" },
{ "key": "CHANGED_KEY", "status": "modified" }
]
}
```
---
### history
Show version history for a secret.
```bash
keyenv history [OPTIONS]
```
#### Arguments
| Argument | Description |
|----------|-------------|
| KEY | The secret key to show history for |
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment (default: development) |
| -l, --limit <N> | Number of entries to show (default: 10) |
#### Examples
```bash
keyenv history DATABASE_URL
# History for DATABASE_URL (development):
# v3 2024-01-15 10:30 user@example.com postgres://prod...
# v2 2024-01-10 14:22 user@example.com postgres://staging...
# v1 2024-01-05 09:00 admin@example.com postgres://dev...
```
#### JSON Output
```bash
keyenv history DATABASE_URL --json
```
```json
{
"key": "DATABASE_URL",
"environment": "development",
"history": [
{
"version": 3,
"changed_at": "2024-01-15T10:30:00Z",
"changed_by": "user@example.com",
"value_preview": "postgres://prod..."
}
]
}
```
> **Note**
>
> Values are partially masked in the output. Use `keyenv get` to retrieve the full value.
## Full Reference
All CLI commands on a single page.
Source: https://keyenv.dev/docs/cli/reference/
Quick reference for all KeyEnv CLI commands.
### Authentication
| Command | Description |
|---------|-------------|
| keyenv login | Authenticate with KeyEnv |
| keyenv logout | Clear stored credentials |
| keyenv whoami | Display current user |
### Projects
| Command | Description |
|---------|-------------|
| keyenv init | Initialize project in current directory |
| keyenv projects | List all projects |
| keyenv switch <project> | Switch to a different project |
### Secrets
| Command | Description |
|---------|-------------|
| keyenv pull | Pull secrets to .env file |
| keyenv push | Push .env secrets to server |
| keyenv list | List secret keys |
| keyenv get <key> | Get a secret value |
| keyenv set <key> <value> | Set a secret |
| keyenv delete <key> | Delete a secret |
| keyenv export | Export secrets to various formats |
### Export
Export secrets to various formats (dotenv, JSON).
| Command | Description |
|---------|-------------|
| keyenv export | Export secrets to stdout |
| keyenv export -e <env> | Export from specific environment |
| keyenv export -f <format> | Export in format (dotenv, json) |
| keyenv export -o <file> | Export to file |
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment to export from (default: development) |
| -f, --format <FORMAT> | Output format: dotenv, json (default: dotenv) |
| -o, --output <FILE> | Write output to file instead of stdout |
#### Examples
```bash
# Export as dotenv to stdout
keyenv export
# Export production secrets as JSON
keyenv export -e production -f json
# Export to a file
keyenv export -o .env.local
```
### Workflow
| Command | Description |
|---------|-------------|
| keyenv run -- <cmd> | Run command with secrets |
| keyenv diff | Compare local and remote |
| keyenv history <key> | View secret history |
### Permissions
| Command | Description |
|---------|-------------|
| keyenv permissions list | List permissions for an environment |
| keyenv permissions set <email> <role> | Set a user's permission (none/read/write/admin) |
| keyenv permissions delete <email> | Remove a user's permission |
| keyenv permissions my | Show your permissions for all environments |
### Tokens
Manage service tokens for CI/CD and programmatic access.
| Command | Description |
|---------|-------------|
| keyenv tokens list | List all service tokens |
| keyenv tokens create --name <name> --scope <scope> | Create a new service token |
| keyenv tokens revoke <id> | Revoke a service token |
| keyenv tokens rotate <id> | Rotate a service token |
#### Options
| Option | Commands | Description |
|--------|----------|-------------|
| -n, --name <NAME> | create | Token name |
| -s, --scope <SCOPE> | create | Token scope: read, write, admin (repeatable) |
| -p, --project <ID> | create | Project ID (defaults to current project) |
| -e, --env <ID> | create | Restrict to a specific environment ID |
| --expires <DAYS> | create | Token expiry in days (omit for never) |
| -y, --yes | revoke | Skip confirmation prompt |
| --grace-period <MINS> | rotate | Grace period in minutes for old token (default: 5, max: 60) |
#### Examples
```bash
# List all tokens
keyenv tokens list
# Create a read-only token for CI
keyenv tokens create --name deploy-ci --scope read
# Create an admin token that expires in 90 days
keyenv tokens create --name admin-token --scope admin --expires 90
# Revoke a token
keyenv tokens revoke st_abc123
# Revoke without confirmation
keyenv tokens revoke st_abc123 --yes
# Rotate a token with 30-minute grace period
keyenv tokens rotate st_abc123 --grace-period 30
```
### Teams
Manage teams and team members.
| Command | Description |
|---------|-------------|
| keyenv team list | List your teams |
| keyenv team create <name> | Create a new team |
| keyenv team show <id> | Show team details and members |
| keyenv team use <id> | Set default team for current session |
| keyenv team invite <email> [role] [--team <team_id>] | Invite a member (default: member) |
| keyenv team role <team> <user> <role> | Update a member's role |
| keyenv team remove <team> <user> | Remove a member from a team |
| keyenv team invitations <team> | List pending invitations |
| keyenv team revoke-invite <team> <invitation> | Revoke a pending invitation |
| keyenv team resend-invite <team> <invitation> | Resend an invitation email |
| keyenv team delete <team> | Delete a team |
| keyenv team audit <team> | View team audit log |
#### Options
| Option | Commands | Description |
|--------|----------|-------------|
| role | invite | Role for invited user: admin or member (default: member) |
| -y, --yes | remove, revoke-invite, delete | Skip confirmation prompt |
#### Examples
```bash
# List all teams
keyenv team list
# Create a new team
keyenv team create "My Team"
# Show team details
keyenv team show team_abc123
# Set default team for the session
keyenv team use team_abc123
# Invite a member
keyenv team invite user@example.com member --team team_abc123
# Invite as admin
keyenv team invite user@example.com admin --team team_abc123
# Change a member's role
keyenv team role team_abc123 user_xyz admin
# Remove a member
keyenv team remove team_abc123 user_xyz
# List pending invitations
keyenv team invitations team_abc123
# Revoke a pending invitation
keyenv team revoke-invite team_abc123 inv_xyz
# Resend an invitation email
keyenv team resend-invite team_abc123 inv_xyz
# Delete a team (requires confirmation)
keyenv team delete team_abc123
# View audit log
keyenv team audit team_abc123
```
### Security
| Command | Description |
|---------|-------------|
| keyenv scan | Scan directory for hardcoded secrets |
| keyenv scan <path> | Scan specific path |
| keyenv scan --severity <level> | Filter by severity (critical, high, medium, low) |
| keyenv scan --json | Output findings as JSON |
| keyenv scan --upload | Upload scan results to KeyEnv for tracking |
| keyenv scan --hook | Install pre-commit hook |
| keyenv scan --hook --remove | Remove pre-commit hook |
### Update
Check for and install CLI updates.
| Command | Description |
|---------|-------------|
| keyenv update check | Check if a new version is available |
| keyenv update install | Download and install the latest version |
#### Examples
```bash
# Check for updates
keyenv update check
# Current version: 0.5.0
# Latest version: 0.6.0
# Run 'keyenv update install' to update
# Install the latest version
keyenv update install
```
### Rotations
Manage automatic secret rotation configurations.
| Command | Description |
|---------|-------------|
| keyenv rotations list | List all rotation configurations |
| keyenv rotations show <id> | Show details of a rotation |
| keyenv rotations trigger <id> | Manually trigger a rotation |
| keyenv rotations history <id> | View rotation execution history |
#### Options
| Option | Description |
|--------|-------------|
| -e, --env <ENV> | Environment (default: development) |
#### Examples
```bash
# List all rotations
keyenv rotations list
# Show rotation details
keyenv rotations show rot_abc123
# Manually trigger a rotation
keyenv rotations trigger rot_abc123
# View rotation history
keyenv rotations history rot_abc123
```
### Shell Completions
| Command | Description |
|---------|-------------|
| keyenv completions <shell> | Generate shell completion script |
Supported shells: `bash`, `zsh`, `fish`, `powershell`, `elvish`
#### Setup
**Bash** (add to `~/.bashrc`):
```bash
source <(keyenv completions bash)
```
**Zsh** (add to `~/.zshrc`):
```bash
# Option 1: Direct source
source <(keyenv completions zsh)
# Option 2: Save to fpath (faster startup)
keyenv completions zsh > ~/.zfunc/_keyenv
# Then ensure ~/.zfunc is in fpath and run: autoload -Uz compinit && compinit
```
**Fish** (run once):
```bash
keyenv completions fish > ~/.config/fish/completions/keyenv.fish
```
**PowerShell** (add to profile):
```powershell
keyenv completions powershell | Out-String | Invoke-Expression
```
### Global Options
| Option | Description |
|--------|-------------|
| --json | JSON output |
| -q, --quiet | Minimal output |
| --no-color | Disable colored output |
| -v, --verbose | Enable verbose output |
| -h, --help | Show help |
| -V, --version | Show version |
### Common Flags
| Flag | Commands | Description |
|------|----------|-------------|
| -e, --env | Most | Target environment |
| -f, --force | pull, push | Overwrite without asking |
### Environment Variables
| Variable | Description |
|----------|-------------|
| KEYENV_TOKEN | Service token for authentication |
| KEYENV_API_URL | Custom API server URL |
### Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Authentication error |
| 3 | Not found |
---
# Web App
## Web App
Manage secrets through the KeyEnv web interface.
Source: https://keyenv.dev/docs/web-app/
The KeyEnv web app provides a visual interface for managing secrets, teams, and projects.
### Overview
Access the web app at [app.keyenv.dev](https://app.keyenv.dev).
#### Key Features
- **Visual secret management** - Create, edit, and delete secrets
- **Team collaboration** - Invite members and manage permissions
- **Audit logs** - Track all changes to your secrets
- **Environment switching** - Easily switch between environments
### Sections
- [Projects](/docs/web-app/projects) - Create and manage projects
- [Environments](/docs/web-app/environments) - Configure environments
- [Secrets](/docs/web-app/secrets) - Manage secret values
- [Teams](/docs/web-app/teams) - Collaborate with your team
- [Service Tokens](/docs/web-app/service-tokens) - Set up CI/CD access
- [Billing](/docs/web-app/billing) - Manage plans and subscriptions
- [Profile](/docs/web-app/profile) - View your profile, security, activity, and account settings
## Projects
Creating and managing projects in the web app.
Source: https://keyenv.dev/docs/web-app/projects/
Projects are the top-level container for your secrets. Each project typically represents one application or service.
### Creating a Project
1. Click the project dropdown in the header
2. Click **New Project**
3. Enter a project name (e.g., "my-api", "frontend")
4. Optionally add a description
5. Click **Create**
Your project is created with a default `development` environment.
### Project Settings
Access project settings by clicking the gear icon next to the project name.
#### General Settings
- **Name**: The display name of your project
- **Description**: Optional description for documentation
- **Project ID**: Unique identifier used by the CLI
#### Danger Zone
- **Delete Project**: Permanently removes the project and all secrets
> **Warning**
>
> Deleting a project cannot be undone. Make sure to export your secrets first if needed.
### Switching Projects
Use the project dropdown in the header to switch between projects. The currently selected project is displayed in the dropdown button.
### Project List
The project dropdown shows all projects you have access to:
- Projects you created
- Projects shared with you by team members
## Environments
Managing environments for different stages of development.
Source: https://keyenv.dev/docs/web-app/environments/
Environments allow you to maintain separate sets of secrets for different stages of your development workflow.
### Default Environment
When you create a project, a `development` environment is created by default. You can add additional environments like `staging` and `production` as needed.
| Environment | Purpose |
|-------------|---------|
| `development` | Local development and testing |
| `staging` | Pre-production testing |
| `production` | Live application |
### Switching Environments
Use the environment tabs at the top of the secrets page to switch between environments.
Each environment maintains its own:
- Secret values
- Version history
- Access logs
### Environment Isolation
Secrets are completely isolated between environments:
```
# development
DATABASE_URL=postgres://localhost/mydb_dev
# staging
DATABASE_URL=postgres://staging-server/mydb_staging
# production
DATABASE_URL=postgres://prod-server/mydb_prod
```
This ensures you never accidentally use production credentials in development.
### Environment Permissions
Control who can access each environment with granular permissions.
#### Permission Levels
| Role | Description |
|------|-------------|
| `none` | No access to the environment |
| `read` | Can view secrets (pull, list, get) |
| `write` | Can view and modify secrets (create, update, delete) |
| `admin` | Full access including managing other users' permissions |
#### Managing Permissions
1. Navigate to an environment in your project
2. Click the **⋮** menu next to the environment tabs
3. Select **Manage Access**
4. Add team members and assign their permission level
> **Note**
>
> Team admins automatically have full access to all environments.
#### Default Permissions
Set default permissions for new team members in **Project Settings → Default Permissions**. When a new member joins the team, they'll automatically receive these permissions for each environment.
### Best Practices
1. **Never copy production secrets to development** - Use separate credentials for each environment
2. **Use similar key names** - Keep the same keys across environments for consistency
3. **Document differences** - Use descriptions to note environment-specific requirements
4. **Restrict production access** - Use environment permissions to limit who can view production secrets
5. **Use read-only for CI/CD** - Service tokens for CI/CD only need `read` access
> **Note**
>
> The CLI defaults to the `development` environment. Use the `-e` flag to target other environments.
## Environment Permissions
Control access to secrets with granular environment-level permissions.
Source: https://keyenv.dev/docs/web-app/permissions/
Environment permissions give you fine-grained control over who can access secrets in each environment. This allows teams to restrict production access while giving developers full access to development environments.
### Permission Roles
Each team member can have one of four permission levels per environment:
| Role | View Secrets | Modify Secrets | Manage Permissions |
|------|--------------|----------------|-------------------|
| `none` | ❌ | ❌ | ❌ |
| `read` | ✅ | ❌ | ❌ |
| `write` | ✅ | ✅ | ❌ |
| `admin` | ✅ | ✅ | ✅ |
> **Note**
>
> Team admins automatically have full access to all environments regardless of individual permission settings.
### Managing Permissions
#### Via the Web App
1. Navigate to your project's secrets page
2. Click the **⋮** menu next to the environment tabs
3. Select **Manage Access**
4. In the modal:
- View current permissions for all team members
- Add new permissions by selecting a team member and role
- Edit existing permissions by clicking on the role badge
- Remove permissions with the delete button
#### Via the CLI
```bash
# List permissions for an environment
keyenv permissions list --env production
# Set a user's permission
keyenv permissions set user@example.com write --env production
# Remove a user's permission
keyenv permissions delete user@example.com --env production
# View your own permissions
keyenv permissions my
```
#### Via the SDK
```typescript
// Node.js
const permissions = await client.listPermissions('project-id', 'production');
await client.setPermission('project-id', 'production', 'user-id', 'write');
```
```python
# Python
permissions = client.list_permissions("project-id", "production")
client.set_permission("project-id", "production", "user-id", "write")
```
### Default Permissions
Configure default permissions that are automatically applied when new team members join.
#### Setting Defaults
1. Go to **Project Settings**
2. Find the **Default Permissions** section
3. Set the default role for each environment
4. Click **Save Changes**
When a new member joins the team, they'll automatically receive these default permissions.
> **Warning**
>
> Default permissions only apply to new team members. Existing members keep their current permissions.
### Service Token Permissions
Service tokens can be scoped to specific environments for additional security:
- **Single-environment tokens**: Create tokens that can only access one environment
- **Read-only tokens**: Use `read` scope for CI/CD that only needs to pull secrets
- **Write tokens**: Use `write` scope only when the token needs to modify secrets
```bash
# Example: CI/CD token with read-only access to production
KEYENV_TOKEN="env_..." keyenv pull --env production
```
### Team Roles and Environment Permissions
KeyEnv uses a two-tier permission model. Understanding how these layers interact is key to setting up secure access for your team.
#### Team Admin vs Environment Permission
**Team role** (`admin` or `member`) is set at the team level and applies across all projects. **Environment permission** (`none`, `read`, `write`, `admin`) is set per-environment within a project.
These two layers interact as follows:
- **Team admins** automatically receive `admin` access to every environment in every project. No environment-level permission is checked. This means team admins can always view secrets, modify secrets, and manage permissions in any environment.
- **Team members** have no implicit access. Their effective permission for a given environment is determined solely by their environment-level permission. If no permission is set, they have `none` (no access).
#### Permission Resolution
When a user tries to access secrets in an environment, the system resolves their effective permission:
1. Check if the user is a team admin. If yes, grant `admin` access (done).
2. Look up the user's environment-level permission for this specific environment.
3. If no explicit permission exists, the effective role is `none`.
This means a team member with `write` on `development` and `read` on `production` can edit dev secrets but only view production secrets. A team admin skips this check entirely.
#### Default Permissions and New Members
When a new member joins the team (by accepting an invitation), default permissions are applied automatically:
1. The system checks each project for configured default permissions.
2. For each environment with a default role, the new member receives that role.
3. If no default is configured for an environment, the member gets `none`.
Only team admins can configure project default permissions. Defaults do not retroactively change existing members' permissions.
#### Permission Cleanup on Member Removal
When a member is removed from a team:
- All their environment-level permissions across all projects are removed
- Access is revoked immediately
- Service tokens created by that user continue to work (revoke them separately if needed)
#### Practical Examples
**Small startup (5 developers, 1 DevOps lead)**
Set up the DevOps lead as a team admin. Add all developers as team members with defaults:
```
development: write (everyone can edit dev secrets)
staging: write (everyone can deploy to staging)
production: read (developers can view but not change production)
```
The DevOps lead, as a team admin, automatically has full access to production for deployments and rotations.
**Agency with client projects**
Use team members for contractors with minimal access:
```
development: write (contractors work in dev)
staging: none (no staging access)
production: none (no production access)
```
Keep at least two internal staff as team admins for full access.
**Large team with environment owners**
Promote environment leads to `admin` on their specific environments:
```
development: Most developers → write, Dev Lead → admin
staging: QA team → write, QA Lead → admin
production: DevOps → admin, Everyone else → read
```
Environment admins can manage permissions for their environment without needing to be team admins.
### Best Practices
#### Principle of Least Privilege
- Give users the minimum access they need
- Use `read` for users who only need to view secrets
- Reserve `admin` for team leads who manage access
#### Production Security
- Limit `write` and `admin` access to production
- Use `read` access for most developers in production
- Require approval workflows for production changes
#### Audit Trail
All permission changes are logged in the audit trail:
- Who changed the permission
- What the previous and new roles were
- When the change occurred
### Common Scenarios
#### Development Team Setup
```
development: All developers → write
staging: All developers → write
production: All developers → read, DevOps → admin
```
#### Contractor Access
```
development: Contractor → write
staging: Contractor → read
production: Contractor → none
```
#### CI/CD Pipeline
```
Service Token: read access to required environments only
```
## Secrets
Managing secrets in the web app.
Source: https://keyenv.dev/docs/web-app/secrets/
The secrets page is where you create, view, and manage your environment variables.
### Viewing Secrets
Secrets are displayed in a list showing:
- **Key**: The environment variable name
- **Value**: Hidden by default (click to reveal)
- **Version**: Current version number
- **Updated**: When it was last modified
### Creating a Secret
1. Click **Add Secret**
2. Enter the key name (e.g., `DATABASE_URL`)
3. Enter the secret value
4. Optionally add a description
5. Click **Save**
#### Key Naming Conventions
- Use UPPERCASE with underscores: `DATABASE_URL`, `API_KEY`
- Be descriptive: `STRIPE_SECRET_KEY` vs just `KEY`
- Group related secrets: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
### Editing a Secret
1. Click on a secret row to select it
2. Click the edit icon or press Enter
3. Modify the value
4. Click **Save**
Each edit creates a new version, preserving the history.
### Viewing Value
Secret values are hidden by default for security. To view:
1. Click the eye icon next to the value
2. The value is revealed
3. Click the eye icon again to hide it
### Version History
Click on a secret to see its version history:
- Previous values (partially masked)
- Who made each change
- When changes were made
### Deleting a Secret
1. Select the secret
2. Click the delete icon
3. Confirm the deletion
> **Warning**
>
> Deleted secrets cannot be recovered. The version history is also removed.
### Bulk Operations
#### Import from .env
1. Click **Import**
2. Paste your `.env` file contents or upload a file
3. Review the secrets to be imported
4. Click **Import**
#### Export to .env
1. Click **Export**
2. Download the `.env` file
> **Note**
>
> For automated sync, use the CLI: `keyenv pull` and `keyenv push`
## Secret Rotation
Automatically rotate database credentials with zero downtime.
Source: https://keyenv.dev/docs/web-app/rotations/
Secret rotation automatically rotates database credentials on a schedule, eliminating manual password management and reducing security risks.
### What Is Secret Rotation?
Secret rotation automatically:
- Creates new database credentials on a configurable schedule
- Updates your environment with the new credentials
- Removes old credentials after successful rotation
- Notifies you via webhooks when rotations occur
### Supported Databases
| Database | Status | Connection Methods |
|----------|--------|-------------------|
| PostgreSQL | Supported | Direct, Lambda Proxy |
| MySQL | Supported | Direct, Lambda Proxy |
#### Connection Methods
**Direct Connection**: KeyEnv connects directly to your database over the internet. Your database must be publicly accessible (with proper firewall rules) or accessible via VPN/peering.
**Lambda Proxy**: For databases in private VPCs or behind firewalls, KeyEnv can execute rotations through an AWS Lambda function deployed in your VPC. The Lambda acts as a secure bridge between KeyEnv and your private database.
### How It Works
KeyEnv uses a **two-secret strategy** for zero-downtime rotations:
1. **Setup**: You provide admin credentials for your database
2. **Two Credentials**: KeyEnv creates and maintains two sets of credentials
3. **Rotation**: When rotating, KeyEnv creates a new credential, verifies it works, then removes the old one
4. **Injection**: The active credentials are automatically injected into your environment
This approach ensures your applications always have valid credentials, even during rotation.
### Injected Secrets
When you create a rotation (e.g., named "main_database"), these secrets are automatically created in your environment:
```bash
MAIN_DATABASE_HOST # Database hostname
MAIN_DATABASE_PORT # Database port
MAIN_DATABASE_DATABASE # Database name
MAIN_DATABASE_USERNAME # Current active username
MAIN_DATABASE_PASSWORD # Current active password
MAIN_DATABASE_URL # Full connection URL
```
The naming convention is your rotation name converted to `UPPER_SNAKE_CASE`.
### Creating a Rotation
1. Go to **Project** → **Rotations** tab
2. Click **Create Rotation**
3. Fill in the wizard steps:
#### Step 1: Database Type
Select PostgreSQL or MySQL.
#### Step 2: Connection Method
Choose how KeyEnv will connect to your database:
| Method | Use Case |
|--------|----------|
| **Direct** | Database is publicly accessible or via VPN |
| **Proxied (Lambda)** | Database is in a private VPC |
#### Step 3: Connection Details
| Field | Description |
|-------|-------------|
| **Host** | Database server hostname or IP |
| **Port** | Database port (5432 for PostgreSQL, 3306 for MySQL) |
| **Database** | Database name to connect to |
| **Admin Username** | Username with permission to create/drop users |
| **Admin Password** | Password for the admin user |
| **SSL Mode** | Connection encryption mode |
##### SSL Mode Options
| Mode | Description |
|------|-------------|
| **Require** | Encrypt connection, don't verify certificate (default) |
| **Verify Full** | Encrypt and verify server certificate + hostname |
| **Verify CA** | Encrypt and verify certificate authority |
| **Disable** | No encryption (only for local development) |
> **Warning**
>
> The admin credentials must have permission to create users, grant permissions, and drop users. These are stored encrypted and never logged.
#### Step 3b: Lambda Proxy Configuration (if proxied)
If you selected proxied connection, you'll need to provide:
| Field | Description |
|-------|-------------|
| **Lambda ARN** | The ARN of your deployed rotation proxy Lambda |
| **AWS Region** | The AWS region where the Lambda is deployed |
| **Shared Secret** | A secret key for HMAC request signing (auto-generated if blank) |
> **Note**
>
> See [Setting Up Lambda Proxy](#setting-up-lambda-proxy) for deployment instructions.
#### Step 4: Rotation Settings
| Setting | Description |
|---------|-------------|
| **Name** | A name for this rotation (becomes prefix for injected secrets) |
| **Rotation Interval** | How often to rotate (1-365 days) |
#### Step 5: Test & Confirm
KeyEnv tests the connection before saving. If the test fails, check your credentials and network connectivity.
### Managing Rotations
#### View Rotation Details
Click on a rotation card to see:
- **Overview**: Current status, next rotation date, injected secrets
- **History**: Past rotation events with timestamps and outcomes
- **Webhooks**: Configured webhook notifications
#### Update Settings
1. Click the rotation card
2. Update the rotation interval or pause/resume the rotation
3. Save changes
#### Trigger Manual Rotation
If you need to rotate credentials immediately:
1. Click the rotation card
2. Click **Rotate Now**
3. Confirm the action
Manual rotations don't affect the scheduled rotation timeline.
#### Pause/Resume Rotation
To temporarily stop automatic rotations:
1. Click the rotation card
2. Toggle the status to **Paused**
Paused rotations won't run on schedule but can still be triggered manually.
#### Delete a Rotation
1. Click the rotation card
2. Click **Delete**
3. Confirm deletion
> **Warning**
>
> Deleting a rotation removes the injected secrets and cleans up created database users. Make sure your applications are updated before deleting.
### Webhooks
Get notified when rotation events occur.
#### Creating a Webhook
1. Click the rotation card
2. Go to the **Webhooks** tab
3. Click **Add Webhook**
4. Enter the webhook URL
5. Select events to receive
#### Webhook Events
| Event | Description |
|-------|-------------|
| `rotation.started` | Rotation process has begun |
| `rotation.completed` | Rotation completed successfully |
| `rotation.failed` | Rotation failed with an error |
#### Webhook Payload
```json
{
"event": "rotation.completed",
"rotation": {
"id": "rot_abc123",
"name": "main_database",
"integration_type": "postgresql"
},
"timestamp": "2026-01-20T12:00:00Z",
"version": 5
}
```
Webhooks include a signature header (`X-KeyEnv-Signature`) for verification.
### Best Practices
1. **Start with longer intervals** - Begin with 30 or 90 day rotations, then shorten as confidence grows
2. **Use webhooks** - Set up notifications to monitor rotation health
3. **Test in staging first** - Verify your application handles credential updates before enabling in production
4. **Monitor rotation history** - Check for failed rotations regularly
5. **Use connection pooling** - Connection pools handle credential changes more gracefully
### Troubleshooting
#### Connection Test Fails
- Verify the database is accessible from KeyEnv's servers
- Check that the admin user has CREATE USER and GRANT permissions
- Ensure the port is open and SSL settings are correct
#### Rotation Fails
Check the rotation history for error details. Common issues:
- **Auth errors**: Admin credentials may have changed or expired
- **Access errors**: Admin user may have lost permissions
- **Network errors**: Database may be temporarily unreachable
#### Application Can't Connect
- Pull the latest secrets: `keyenv pull`
- Restart your application to pick up new environment variables
- Verify the rotation completed successfully in the history tab
### Setting Up Lambda Proxy
For databases in private VPCs that can't be accessed directly from the internet, you can deploy a Lambda function in your VPC to act as a rotation proxy.
#### Architecture
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ KeyEnv API │────▶│ AWS Lambda │────▶│ Your Database │
│ (rotation svc) │ │ (your VPC) │ │ (private) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
```
#### Deployment Steps
1. **Create an AWS Lambda function** in your VPC with access to your database subnet
2. **Deploy the KeyEnv rotation proxy code** (available in our GitHub repository)
3. **Configure VPC settings** to allow the Lambda to connect to your database
4. **Note the Lambda ARN** and provide it when creating the rotation
#### Security
The Lambda proxy uses HMAC-SHA256 signed requests:
- Requests include a timestamp and signature
- Timestamps are validated within a 5-minute window (replay protection)
- Shared secret is stored encrypted in KeyEnv, never logged
- All communication uses TLS encryption
> **Note**
>
> Contact support for detailed Lambda deployment templates and assistance with VPC configuration.
### Security
- Admin credentials are encrypted at rest using AES-256-GCM
- Credentials are never logged or exposed in API responses
- Each rotation creates unique, randomly-generated passwords
- Old credentials are dropped from the database after successful rotation
- Lambda proxy requests are HMAC-signed with timestamp validation
## Teams
Create teams, manage members, and control access to your projects.
Source: https://keyenv.dev/docs/web-app/teams/
Teams are the organizational unit in KeyEnv. Every project belongs to a team, and team membership determines who can access your secrets. When you sign up, a personal team is created automatically.
### Team Lifecycle
#### Creating a Team
1. Click your team name in the sidebar
2. Click **Create Team**
3. Enter a team name (up to 100 characters)
4. Click **Create**
The creator automatically becomes the team's first **admin**. New teams start on the Free plan.
#### Viewing Team Details
Navigate to **Team** in the sidebar to see:
- Team name and plan
- All current members with their roles
- Pending invitations
#### Renaming a Team
Team admins can rename a team from the team settings page. Click the edit icon next to the team name, enter the new name, and save.
#### Deleting a Team
Team deletion is handled by system administrators. If you need to delete a team, contact support. Deleting a team permanently removes all projects, secrets, and member associations.
> **Warning**
>
> Team deletion cannot be undone. Make sure to export any secrets you need before requesting deletion.
### Team Roles
KeyEnv has two team-level roles: **admin** and **member**.
| Capability | Admin | Member |
|---|---|---|
| View team members and invitations | Yes | Yes |
| Access all environments (bypasses env permissions) | Yes | No |
| Invite and remove members | Yes | No |
| Change member roles | Yes | No |
| Create and delete projects | Yes | No |
| Manage billing and plan | Yes | No |
| Set default permissions | Yes | No |
| View audit logs | Yes | No |
| View and edit secrets | Yes | Per-environment |
| Manage environment permissions | Yes | Only if granted `admin` on that environment |
> **Note**
>
> Team admins automatically have full access to all environments in every project. Regular members get access based on their per-environment permissions. See [Environment Permissions](/docs/web-app/permissions) for details.
#### Changing a Member's Role
1. Go to **Team** in the sidebar
2. Find the member in the list
3. Click the role dropdown next to their name
4. Select the new role
You cannot demote the last admin. Every team must have at least one admin at all times.
### Inviting Members
Only team admins can invite new members.
#### Sending an Invitation
1. Go to **Team** in the sidebar
2. Click **Invite Member**
3. Enter the invitee's email address
4. Select a role (`admin` or `member`)
5. Click **Send Invite**
The invitee receives an email with a link to join. If they do not have a KeyEnv account, they will be prompted to create one.
> **Note**
>
> Members receive email notifications when invited to a team, when their role changes, and when they are removed from a team.
#### Invitation Expiration
Invitations expire after **30 days**. If an invitation expires:
- The invitee can no longer accept it
- An admin must resend the invitation to generate a fresh link
Resending refreshes both the token and the expiration date.
#### Invitations and Member Limits
Pending invitations count toward your team's member limit. On the Free plan (1 member limit), you cannot send an invitation because the creator already fills the slot. Upgrade to Pro for unlimited members.
#### Managing Pending Invitations
Admins can view, resend, and revoke pending invitations:
- **View**: Go to the **Invitations** tab on the team page
- **Resend**: Click the resend button next to the invitation
- **Revoke**: Click the revoke button to cancel a pending invitation
### Removing Members
Team admins can remove any member from the team:
1. Go to **Team** in the sidebar
2. Find the member in the list
3. Click the remove button
4. Confirm the removal
Non-admin members can only remove themselves (leave the team). They cannot remove other members.
> **Warning**
>
> Removed members immediately lose access to all project secrets. Their environment-level permissions are cleaned up automatically.
You cannot remove the last admin from a team. The sole admin must promote another member to admin before leaving.
### Team Roles and Environment Permissions
KeyEnv uses a two-tier permission model:
1. **Team role** (`admin` or `member`) -- controls team-level operations
2. **Environment permission** (`none`, `read`, `write`, or `admin`) -- controls per-environment secret access
How they interact:
- **Team admins** bypass environment permissions entirely. They have full `admin` access to every environment in every project.
- **Team members** rely on their per-environment permissions. If a member has no permission set for an environment, they have `none` (no access).
#### Default Permissions
Only team admins can configure default permissions for each environment. When a new member joins the team, they automatically receive these defaults. For example, you might set:
- `development` -> `write` (all new members can edit dev secrets)
- `staging` -> `read` (all new members can view staging)
- `production` -> `none` (no production access by default)
See [Environment Permissions](/docs/web-app/permissions) for full details on managing per-environment access.
### Plan Limits
Team capabilities depend on your plan:
| Resource | Free | Pro | Enterprise |
|---|---|---|---|
| Team members | 1 | Unlimited | Unlimited |
| Projects | 3 | Unlimited | Unlimited |
| Secrets per environment | 100 | Unlimited | Unlimited |
| Environments per project | 3 | Unlimited | Unlimited |
When you reach a limit, you can still use existing resources but cannot create new ones. Upgrade to Pro to remove all limits.
See [Billing](/docs/web-app/billing) for details on upgrading and managing your plan.
### Audit Trail
All team actions are logged:
- Team created
- Member invited, accepted, removed
- Role changes
- Invitation sent, resent, or revoked
Access the audit log from the team settings page. Only team admins can view audit logs.
### Best Practices
1. **Keep multiple admins** -- If your sole admin loses access, no one can manage the team. Always have at least two admins for critical teams.
2. **Review access regularly** -- Remove members who no longer need access. Check pending invitations and revoke stale ones.
3. **Use service tokens for CI/CD** -- Do not share personal credentials with automated systems. Create scoped [service tokens](/docs/web-app/service-tokens) instead.
4. **Set default permissions thoughtfully** -- Configure project defaults so new members get appropriate access without manual setup.
5. **Restrict production access** -- Give most members `read` or `none` for production and reserve `write`/`admin` for senior engineers and DevOps.
## Service Tokens
Setting up service tokens for CI/CD.
Source: https://keyenv.dev/docs/web-app/service-tokens/
Service tokens provide secure access for automated systems like CI/CD pipelines.
### What Are Service Tokens?
Service tokens are API keys that:
- Authenticate without user interaction
- Have configurable scope (one or more projects, optional environment restriction)
- Support three permission levels: `read`, `write`, and `admin`
- Can optionally expire after a set number of days
- Are logged separately in the audit trail
- Track last usage time for security auditing
### Token Scopes
Every service token requires at least one scope. Scopes control what the token is allowed to do:
| Scope | Description |
|-------|-------------|
| `read` | View and pull secrets (read-only access) |
| `write` | Create, update, and delete secrets; create, rotate, and revoke tokens |
| `admin` | Full administrative access to projects and environments |
You can assign multiple scopes to a single token. For example, a CI/CD deploy token might need both `read` and `write`, while a monitoring tool only needs `read`.
### Creating a Service Token
1. Navigate to **Tokens** in the project navigation
2. Click **Create Token**
3. Enter a name (e.g., "GitHub Actions - Production")
4. Select one or more projects to grant access to
5. Optionally restrict access to a specific environment within the selected projects
6. Choose the scopes the token should have
7. Optionally set an expiration (in days)
8. Click **Create**
> **Warning**
>
> Copy the token immediately! It's only shown once.
#### Multi-Project Scoping
Tokens can be scoped to **multiple projects** simultaneously, as long as all projects belong to the same team. This is useful when a single CI/CD pipeline deploys across several related projects.
#### Environment Scoping
By default, a token has access to all environments within its scoped projects. You can optionally restrict a token to a **single environment** (e.g., only `production`). This is recommended for production deploy tokens that should not be able to read staging or development secrets.
#### Token Expiration
By default, tokens never expire. When creating a token, you can set `expires_in_days` to have the token automatically expire after a given number of days. This is useful for:
- Temporary CI tokens for short-lived feature branches
- Contractor access that should automatically end
- Compliance requirements that mandate periodic credential rotation
For example, a token with `expires_in_days: 7` will stop working 7 days after creation.
### Token Format
Service tokens start with `env_` followed by a random string:
```
env_abc123def456...
```
### Using Service Tokens
#### In CI/CD
Set the token as an environment variable:
```yaml
# GitHub Actions
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
steps:
- run: keyenv pull -e production
```
#### With the CLI
```bash
# Set the token
export KEYENV_TOKEN="env_abc123..."
# Now use CLI commands
keyenv pull
```
#### Programmatic Access
```bash
# Login with token
keyenv login --token "env_abc123..."
```
### Managing Tokens
#### View Tokens
The tokens list shows:
- Token name
- Projects and environments it can access
- Scopes assigned
- When it was created
- Last used date
> **Note**
>
> Tokens track `last_used_at` timestamps automatically. Use this to identify unused tokens that can be safely revoked.
#### Revoke a Token
1. Find the token in the list
2. Click **Revoke**
3. Confirm revocation
Revoked tokens immediately stop working.
#### Rotate a Token
Token rotation creates a new token while keeping the old one valid during a grace period. This allows zero-downtime updates across your CI/CD pipelines.
1. Find the token in the list
2. Click **Rotate**
3. Choose a grace period (default: 5 minutes, max: 60 minutes)
4. Copy the new token and update your systems
5. The old token automatically expires after the grace period
> **Note**
>
> During the grace period, both old and new tokens are valid. This prevents CI/CD job failures while you update your secrets.
**Via API:**
```bash
curl -X POST https://api.keyenv.dev/tokens/{token_id}/rotate \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"grace_period_minutes": 10}'
```
Response:
```json
{
"new_token": {
"token": "env_newtoken123...",
"id": "tok_abc123"
},
"old_token_expires_at": "2026-01-23T12:10:00Z"
}
```
### Security Notifications
Team admins receive email notifications when service tokens are created, rotated, or revoked. These alerts include the token name and the email of the user who performed the action, helping teams stay aware of credential changes.
### Service Token Limitations
Service tokens are designed for automated access to secrets and cannot perform all operations available to authenticated users. Specifically, service tokens **cannot**:
- Manage team members or invitations
- Access billing endpoints
- Change team-level permission defaults
These operations require a user session with the appropriate team admin role.
### Security Best Practices
1. **One token per use case** - Create separate tokens for different CI/CD workflows
2. **Limit scope** - Only grant access to needed projects and environments
3. **Use the narrowest scope** - Prefer `read` over `write` when the token only needs to pull secrets
4. **Set expiration for temporary access** - Use `expires_in_days` for short-lived tokens
5. **Rotate regularly** - Use the rotation feature for zero-downtime updates
6. **Never commit tokens** - Use your CI/CD's secret management
7. **Monitor usage** - Check `last_used_at` timestamps and audit logs for unexpected access
8. **Restrict to specific environments** - Use environment scoping to limit blast radius
## Billing
Manage your team's plan, upgrade, and understand usage limits.
Source: https://keyenv.dev/docs/web-app/billing/
KeyEnv offers three plan tiers. Each team has its own plan and billing. Only team admins can view and manage billing.
### Plan Tiers
#### Free
The default plan for every new team. Includes:
| Resource | Limit |
|---|---|
| Team members | 1 |
| Projects | 3 |
| Secrets per environment | 100 |
| Environments per project | 3 |
The Free plan is suitable for personal projects and solo developers. All core features (encryption, CLI, environment permissions, audit trail) are included.
#### Team
For teams that need collaboration and higher limits. Includes:
| Resource | Limit |
|---|---|
| Team members | Unlimited |
| Projects | Unlimited |
| Secrets per environment | Unlimited |
| Environments per project | Unlimited |
**Pricing**: $4/user/month or $40/user/year ($3.33/month, save 17%). Billed per active team member -- the seat count adjusts automatically when members join or leave.
#### Enterprise
For organizations with advanced requirements. Includes everything in Team plus:
- Priority support
- Custom integrations
- SLA guarantees
Contact us at [support@keyenv.dev](mailto:support@keyenv.dev) for Enterprise pricing.
### Free Trial
New teams receive a **14-day free trial** of Team plan features when they first sign up. During the trial:
- All Team plan limits are available (unlimited projects, secrets, members, and environments)
- No payment method is required
- An email notification is sent **3 days before the trial ends**
- When the trial expires, the team automatically downgrades to the Free plan
> **Note**
>
> You can upgrade to a paid Team plan at any time during the trial. If you upgrade, the trial ends immediately and billing begins.
### Upgrading to Team
Only team admins can upgrade the plan.
1. Go to **Team** in the sidebar
2. Click **Billing** or **Upgrade**
3. Choose monthly or annual billing
4. Complete payment through the Stripe checkout page
5. Your plan upgrades immediately after payment
The upgrade takes effect instantly. All limits are lifted and you can invite members, create projects, and add secrets without restrictions.
### Subscription States
Your subscription can be in one of the following states:
| State | Description |
|---|---|
| `active` | Subscription is current and fully paid. All Team plan features are available. |
| `trialing` | Team is in the 14-day free trial period. All Team plan features are available. |
| `past_due` | A payment has failed. The system will retry automatically. Features remain available while retries are in progress. |
| `canceled` | Subscription has been canceled. The team reverts to the Free plan at the end of the current billing period. |
### Managing Your Subscription
After upgrading, team admins can manage the subscription through the Stripe billing portal:
1. Go to **Team** in the sidebar
2. Click **Billing**
3. Click **Manage Subscription**
From the billing portal you can:
- Update your payment method
- View invoices and payment history
- Switch between monthly and annual billing
- Cancel your subscription
### Downgrading
When you cancel your Team subscription, the following happens:
- Your plan reverts to Free at the end of the current billing period
- **Existing resources are kept** -- your projects, secrets, members, and environments remain intact
- **New creation is blocked** -- if your usage exceeds Free plan limits, you cannot create new resources of that type until you reduce usage or re-upgrade
- Team admins receive a notification about the over-limit state
> **Note**
>
> KeyEnv never deletes your data on downgrade. Your existing secrets and projects remain accessible. You just cannot create new ones beyond Free plan limits.
### Over-Limit State
If your team's usage exceeds the plan limits (typically after a downgrade from Team to Free), you enter an over-limit state:
- A warning banner appears in the web app
- The API returns a `402 Payment Required` error when attempting to create resources that are over the limit
- Existing resources continue to work normally (read, update, delete)
#### Resolving Over-Limit
To resolve an over-limit state, you can either:
1. **Reduce usage** -- Delete projects, secrets, or environments to bring usage within Free plan limits
2. **Remove members** -- Remove team members to get within the 1-member Free limit
3. **Upgrade** -- Re-upgrade to Team to remove all limits
### Sponsored Teams
In some cases, a KeyEnv administrator may sponsor a team, granting it Team features at no cost. Sponsored teams:
- Have all Team plan limits (unlimited everything)
- Do not need a Stripe subscription
- Cannot be charged through the checkout flow (checkout is blocked for sponsored teams)
- May include an optional note from the administrator explaining the sponsorship
### Email Notifications
KeyEnv sends email notifications for the following billing events:
- **Subscription created** -- when a team upgrades to the Team plan
- **Trial ending** -- sent 3 days before the free trial expires
- **Payment failed** -- when a payment attempt is unsuccessful (includes the next retry date)
- **Subscription renewed** -- when a subscription is successfully renewed at the start of a new billing period
### Viewing Usage
Any team member can view the team's current resource usage:
1. Go to **Team** in the sidebar
2. The usage section shows current counts and limits for:
- Projects
- Team members
- Secrets (highest count across all environments)
- Environments (highest count across all projects)
Usage warnings appear when you reach 80% of a limit. At-limit indicators appear when you have reached the maximum.
## Profile
View your profile information, manage security settings, review activity, and control your account.
Source: https://keyenv.dev/docs/web-app/profile/
The profile page is your personal hub in KeyEnv. Access it by clicking your avatar in the sidebar. It is organized into four tabs: General, Security, Activity, and Account.
### General
The General tab shows your profile information and team memberships.
#### Profile Information
Your profile card displays:
- **Avatar** -- Your profile picture (synced from your sign-in provider)
- **Name** -- Your full name
- **Email** -- Your primary email address
- **Member since** -- The date you created your KeyEnv account
To edit your name, avatar, or email, click **Edit Profile**. This opens your Clerk account settings in a new tab where you can update your personal information.
#### Team Memberships
Below your profile card, you can see every team you belong to along with:
- **Team name**
- **Your role** -- `admin` or `member`
- **Join date** -- When you joined that team
This gives you a quick overview of your access across all teams without navigating to each one individually.
### Security
The Security tab lets you review your sign-in methods, two-factor authentication status, and active sessions.
#### Connected Accounts
This section lists all sign-in methods linked to your account:
- **Password** -- Whether email/password sign-in is enabled or not set
- **OAuth providers** -- Connected accounts such as Google, GitHub, Microsoft, or Apple, along with the email address associated with each
#### Two-Factor Authentication
Shows whether 2FA is currently enabled or disabled. Click **Enable 2FA** (or **Manage 2FA** if already enabled) to configure two-factor authentication through your account security settings. This opens Clerk's security page in a new tab.
> **Note**
>
> Two-factor authentication adds an extra layer of security by requiring a code from your authenticator app each time you sign in. It is strongly recommended for all users.
#### Active Sessions
Lists all devices and browsers where you are currently signed in. Each session shows:
- **Browser name and version**
- **Location** (city and country)
- **IP address**
- **Last active time**
Your current session is labeled with a **Current** badge. You can revoke any other session by clicking the **Revoke** button, which immediately signs you out of that device.
> **Warning**
>
> Revoking a session takes effect immediately. The signed-in device will need to authenticate again to regain access.
### Activity
The Activity tab displays a chronological log of your actions across all teams.
#### Viewing Activity
Activity is displayed in a table with the following columns:
| Column | Description |
|---|---|
| Timestamp | When the action occurred |
| Team | Which team the action belongs to |
| Action | The type of action (e.g., created, updated, deleted) |
| Details | The affected resource name or identifier |
Actions are color-coded by category:
- **Create** actions (e.g., created a project, added a secret)
- **Read** actions (e.g., accessed secrets)
- **Update** actions (e.g., updated a secret, changed a role)
- **Delete** actions (e.g., deleted a project, removed a member)
#### Filtering
Click the **Filters** button to narrow down your activity log. Available filters:
- **Action** -- Filter by a specific action type from the dropdown
- **Start Date** -- Show only activity from this date onward
- **End Date** -- Show only activity up to this date
Click **Apply Filters** to update the results, or **Clear** to remove all filters.
#### Pagination
Activity logs are paginated at 25 entries per page. When there are multiple pages, navigation controls appear at the bottom of the table showing:
- The range of entries currently displayed (e.g., "Showing 1 to 25 of 142")
- Page number buttons for direct navigation
- Previous and next arrows
### Account
The Account tab provides data privacy controls and account deletion.
#### Data Export
You can request a full export of your KeyEnv data. The export includes:
- Account information
- Projects and environments
- Secret names and metadata (values remain encrypted)
- Team memberships
- Audit logs
- API token metadata
To export your data:
1. Click **Export** on the Data Export card
2. Review what is included in the export
3. Click **Request Export**
4. You will receive an email notification when the export is ready
Once the export is ready, return to this page and click **Download** to save the file. Exports have an expiration date -- if an export expires, you can request a new one.
> **Note**
>
> Secret values are exported in encrypted form for security. The export contains metadata about your secrets, not the plaintext values.
#### Account Deletion
You can permanently delete your KeyEnv account from the Danger Zone section.
Deleting your account removes:
- Your account and profile
- All projects you own
- All secrets in your projects
- Team memberships
- API tokens
- Audit history
To delete your account:
1. Click **Delete** on the Delete Account card
2. Review the list of data that will be removed
3. Type **DELETE** in the confirmation field
4. Click **Delete My Account**
> **Warning**
>
> Account deletion cannot be undone. All your data is permanently removed from KeyEnv's servers. Export your data first if you need a copy.
---
# SDKs & Integrations
## SDKs & Integrations
Official SDKs and integrations for KeyEnv.
Source: https://keyenv.dev/docs/sdks/
Use KeyEnv in your applications with our official SDKs and integrations.
### SDKs
- [Node.js SDK](/docs/sdks/nodejs): TypeScript/JavaScript SDK for server-side apps
- [Python SDK](/docs/sdks/python): Python SDK with full type annotations
- [Go SDK](/docs/sdks/go): Go SDK with full type safety
- [Rust SDK](/docs/sdks/rust): Rust SDK with async/await support
- [Java SDK](/docs/sdks/java): Java SDK with Java 11+ and async support (Beta)
- [PHP SDK](/docs/sdks/php): PHP SDK for PHP 8.0+ applications (Beta)
- [Ruby SDK](/docs/sdks/ruby): Ruby SDK for Ruby 3.0+ applications (Beta)
- [.NET SDK](/docs/sdks/dotnet): .NET SDK for .NET 6.0+ with async patterns (Beta)
### Runtimes
- [Bun](/docs/sdks/bun): Use KeyEnv with Bun applications
- [Deno](/docs/sdks/deno): Use KeyEnv with Deno applications
### CI/CD Integrations
- [GitHub Action](/docs/sdks/github-action): Inject secrets into GitHub Actions workflows
- [Secret Scanner Action](/docs/sdks/scan-action): Scan for hardcoded secrets in your codebase
- [Bitbucket Pipelines](/docs/sdks/bitbucket-pipelines): Inject secrets into Bitbucket Pipelines
### Serverless
- [AWS Lambda Layer](/docs/sdks/aws-lambda): Pre-built layer for Lambda functions
- [Azure Functions](/docs/sdks/azure-functions): Use KeyEnv with Azure Functions
- [Google Cloud Functions](/docs/sdks/google-cloud-functions): Use KeyEnv with Cloud Functions
- [Netlify Build Plugin](/docs/sdks/netlify): Auto-inject secrets during Netlify builds
### Framework Integrations
- [Next.js](/docs/sdks/nextjs): Server Components, API Routes, and Vercel deployment
- [Django](/docs/sdks/django): Django settings.py integration with environment-aware config
- [Laravel](/docs/sdks/laravel): Service Provider, Facade, and Artisan commands for Laravel
- [Spring Boot](/docs/sdks/spring-boot): Auto-configuration, @Value injection, and ConfigurationProperties
- [Rails](/docs/sdks/rails): Rails initializer setup with credentials and database.yml integration
### Platform Integrations
- [Kubernetes (ESO)](/docs/guides/kubernetes): Sync secrets to K8s via External Secrets Operator
- [Docker](/docs/guides/docker): Use KeyEnv with Docker and docker-compose
- [Vercel](/docs/guides/vercel): Deploy to Vercel with KeyEnv secrets
- [Railway](/docs/guides/railway): Sync secrets to Railway projects
### When to Use What
| Use Case | Recommended |
|----------|-------------|
| Local development | CLI (`keyenv pull`, `keyenv run`) |
| Node.js/TypeScript apps | Node.js SDK |
| Python apps | Python SDK |
| Java apps | Java SDK |
| PHP apps | PHP SDK |
| Ruby apps | Ruby SDK |
| .NET/C# apps | .NET SDK |
| Next.js apps | Next.js integration (Node.js SDK) |
| Django apps | Django integration (Python SDK) |
| Laravel apps | Laravel integration (PHP SDK) |
| Spring Boot apps | Spring Boot integration (Java SDK) |
| Rails apps | Rails integration (Ruby SDK) |
| ASP.NET Core apps | .NET SDK |
| Go apps | Go SDK |
| Rust apps | Rust SDK |
| Bun apps | Node.js SDK or CLI |
| Deno apps | CLI or direct API |
| GitHub Actions (inject secrets) | GitHub Action |
| GitHub Actions (scan for secrets) | Secret Scanner Action |
| Bitbucket Pipelines | Bitbucket Pipe |
| Other CI/CD | CLI |
| AWS Lambda | Lambda Layer |
| Azure Functions | Azure Functions integration |
| Google Cloud Functions | Cloud Functions integration |
| Netlify | Netlify Build Plugin |
| Vercel | Next.js integration or Node.js SDK |
| Scripts & automation | SDK or CLI |
| Docker builds | CLI or GitHub Action |
| Kubernetes | External Secrets Operator (ESO) integration |
| Security scanning | Secret Scanner Action or CLI (`keyenv scan`) |
### Authentication
All SDKs use **service tokens** for authentication. Create a token in the KeyEnv dashboard:
1. Go to **Settings > Service Tokens**
2. Click **Create Token**
3. Select scope (project-specific recommended)
4. Copy the token and store it securely
```bash
# Set as environment variable
export KEYENV_TOKEN="your-service-token"
```
## API Reference
Complete REST API documentation for KeyEnv
Source: https://keyenv.dev/docs/sdks/api-reference/
The KeyEnv API is a RESTful HTTP API that provides programmatic access to manage projects, environments, secrets, teams, and service tokens.
### Base URL
```
https://api.keyenv.dev
```
### Authentication
The API supports two authentication methods:
#### Bearer Token (JWT)
For web app and CLI authentication using Clerk-issued JWTs:
```bash
Authorization: Bearer
```
#### Service Token
For CI/CD and programmatic access, use service tokens (prefixed with `env_`):
```bash
Authorization: Bearer env_
```
Service tokens have scoped access to specific projects and environments with `read` and/or `write` permissions.
### Rate Limiting
API requests are rate limited to **60 requests per minute** per user/token.
Rate limit headers are included in responses:
| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per minute |
| `X-RateLimit-Remaining` | Remaining requests in current window |
| `X-RateLimit-Reset` | Unix timestamp when the limit resets |
### Error Handling
All errors follow a consistent format:
```json
{
"error": "Human-readable error message"
}
```
Common HTTP status codes:
| Code | Description |
|------|-------------|
| 400 | Bad request - invalid input |
| 401 | Unauthorized - missing or invalid authentication |
| 403 | Forbidden - insufficient permissions |
| 404 | Resource not found |
| 409 | Conflict - resource already exists |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
### OpenAPI Specification
The complete OpenAPI specification is published alongside these docs:
- **YAML**: [https://keyenv.dev/openapi.yaml](/openapi.yaml)
- **JSON**: [https://keyenv.dev/openapi.json](/openapi.json)
Import either file into [Swagger Editor](https://editor.swagger.io/), [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/), or an AI agent to explore the API programmatically.
> **Note**
>
> The [API Reference](/docs/api) section documents every endpoint, parameter, and response schema. It is generated from this specification, so it never drifts from the running API.
### Key Endpoints
#### Health Check
```bash
GET /health
```
Returns API health status. No authentication required.
#### Projects
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/projects` | List all projects |
| POST | `/api/v1/projects` | Create a project |
| GET | `/api/v1/projects/{id}` | Get a project |
| PATCH | `/api/v1/projects/{id}` | Update a project |
| DELETE | `/api/v1/projects/{id}` | Delete a project |
#### Environments
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/projects/{id}/environments` | List environments |
| POST | `/api/v1/projects/{id}/environments` | Create an environment |
| GET | `/api/v1/projects/{id}/environments/{env}` | Get an environment |
| DELETE | `/api/v1/projects/{id}/environments/{env}` | Delete an environment |
#### Secrets
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/projects/{id}/environments/{env}/secrets` | List secrets |
| POST | `/api/v1/projects/{id}/environments/{env}/secrets` | Create a secret |
| GET | `/api/v1/projects/{id}/environments/{env}/secrets/{key}` | Get a secret |
| PUT | `/api/v1/projects/{id}/environments/{env}/secrets/{key}` | Update a secret |
| DELETE | `/api/v1/projects/{id}/environments/{env}/secrets/{key}` | Delete a secret |
| GET | `/api/v1/projects/{id}/environments/{env}/secrets/export` | Export secrets (JSON) |
| POST | `/api/v1/projects/{id}/environments/{env}/secrets/bulk` | Bulk import |
#### Service Tokens
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/tokens` | List tokens |
| POST | `/api/v1/tokens` | Create a token |
| DELETE | `/api/v1/tokens/{id}` | Delete a token |
| POST | `/api/v1/tokens/{id}/rotate` | Rotate a token |
#### Permissions
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/projects/{id}/my-permissions` | Get my permissions |
| GET | `/api/v1/projects/{id}/environments/{env}/permissions` | List permissions |
| PUT | `/api/v1/projects/{id}/environments/{env}/permissions/{userId}` | Set permission |
| DELETE | `/api/v1/projects/{id}/environments/{env}/permissions/{userId}` | Delete permission |
#### Teams
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/teams` | List teams |
| POST | `/api/v1/teams` | Create a team |
| GET | `/api/v1/teams/{id}` | Get a team |
| POST | `/api/v1/teams/{id}/members` | Invite a member |
| DELETE | `/api/v1/teams/{id}/members/{userId}` | Remove a member |
#### Audit Logs
Requires team admin role. Regular members receive `403 Forbidden`.
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/audit` | List audit logs (admin only) |
| GET | `/api/v1/teams/{id}/audit` | List team audit logs (admin only) |
#### Additional Endpoints
The API also includes endpoints for:
- **Billing & Usage**: `/api/v1/teams/{id}/usage`, `/api/v1/teams/{id}/billing` - Team usage metrics and billing information
- **Team Invitations**: `/api/v1/teams/{id}/invitations` - Manage pending team invitations
- **Account Management**: `/api/v1/account`, `/api/v1/account/data-export` - Account settings and data export
- **Secret Rotations**: `/api/v1/rotations/` - Configure automatic secret rotation
- **CLI Authentication**: `/api/v1/auth/cli/` - Device authorization flow for CLI login
Refer to the [OpenAPI specification](https://github.com/keyenv/keyenv/blob/main/api/openapi.yaml) for complete endpoint documentation.
### Example: List Secrets
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/production/secrets" \
-H "Authorization: Bearer env_your_token_here"
```
Response:
```json
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "DATABASE_URL",
"value": "postgres://...",
"version": 3,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T14:45:00Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"key": "API_KEY",
"value": "sk_live_...",
"version": 1,
"inherited_from": "development",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
]
}
```
### Example: Create a Secret
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/production/secrets" \
-H "Authorization: Bearer env_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"key": "NEW_SECRET",
"value": "secret_value_here"
}'
```
Response:
```json
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440002",
"key": "NEW_SECRET",
"version": 1,
"created_at": "2024-01-21T09:00:00Z",
"updated_at": "2024-01-21T09:00:00Z"
}
}
```
### Example: Export Secrets
The export endpoint returns secrets in JSON format:
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/production/secrets/export" \
-H "Authorization: Bearer env_your_token_here"
```
Response:
```json
{
"data": [
{
"key": "DATABASE_URL",
"value": "postgres://user:pass@localhost:5432/db"
},
{
"key": "API_KEY",
"value": "sk_live_abc123"
},
{
"key": "REDIS_URL",
"value": "redis://localhost:6379",
"inherited_from": "development"
}
]
}
```
The `inherited_from` field is present when a secret is inherited from a parent environment.
### External Secrets Operator (ESO)
KeyEnv provides ESO-compatible webhook endpoints for Kubernetes integration:
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/eso/secret` | Get single secret |
| GET | `/api/v1/eso/secrets` | Get all secrets (for dataFrom) |
See the [Kubernetes ESO Integration Guide](/docs/sdks/kubernetes-eso) for setup instructions.
### SDKs
For easier integration, use our official SDKs:
- [Node.js SDK](/docs/sdks/nodejs)
- [Python SDK](/docs/sdks/python)
- [Go SDK](/docs/sdks/go)
- [Rust SDK](/docs/sdks/rust)
The SDKs handle authentication, error handling, and provide type-safe interfaces to the API.
## Node.js SDK
Official Node.js/TypeScript SDK for KeyEnv.
Source: https://keyenv.dev/docs/sdks/nodejs/
Official Node.js SDK for KeyEnv with full TypeScript support.
### Installation
```bash
npm install @keyenv/node
```
Or with other package managers:
```bash
yarn add @keyenv/node
pnpm add @keyenv/node
```
### Quick Start
```typescript
import { KeyEnv } from '@keyenv/node';
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
// Load secrets into process.env
await client.loadEnv('your-project-id', 'production');
console.log(process.env.DATABASE_URL);
```
### Initialize the Client
```typescript
import { KeyEnv } from '@keyenv/node';
const client = new KeyEnv({
token: 'your-service-token',
timeout: 30000, // optional, default 30s
});
```
### Loading Secrets
#### Load into process.env
The simplest way to use secrets in your application:
```typescript
const count = await client.loadEnv('project-id', 'production');
console.log(`Loaded ${count} secrets`);
// Now use them
console.log(process.env.DATABASE_URL);
console.log(process.env.API_KEY);
```
#### Export as Object
Get secrets as a key-value object:
```typescript
const env = await client.exportSecretsAsObject('project-id', 'production');
console.log(env.DATABASE_URL);
console.log(env.API_KEY);
```
#### Export as Array
Get secrets with metadata:
```typescript
const secrets = await client.exportSecrets('project-id', 'production');
for (const secret of secrets) {
console.log(`${secret.key}=${secret.value}`);
}
```
### Managing Secrets
#### Get a Single Secret
```typescript
const secret = await client.getSecret('project-id', 'production', 'DATABASE_URL');
console.log(secret.value);
console.log(secret.description);
```
#### Set a Secret
Creates or updates a secret:
```typescript
await client.setSecret('project-id', 'production', 'API_KEY', 'sk_live_...');
// With description
await client.setSecret('project-id', 'production', 'API_KEY', 'sk_live_...', 'Production API key');
```
#### Delete a Secret
```typescript
await client.deleteSecret('project-id', 'production', 'OLD_KEY');
```
### Bulk Operations
#### Bulk Import
Import multiple secrets at once:
```typescript
const result = await client.bulkImport('project-id', 'development', [
{ key: 'DATABASE_URL', value: 'postgres://localhost/mydb' },
{ key: 'REDIS_URL', value: 'redis://localhost:6379' },
{ key: 'API_KEY', value: 'sk_test_...', description: 'Test API key' },
], { overwrite: true });
console.log(`Created: ${result.created}, Updated: ${result.updated}`);
```
#### Generate .env File
```typescript
import { writeFileSync } from 'fs';
const envContent = await client.generateEnvFile('project-id', 'production');
writeFileSync('.env', envContent);
```
### Projects & Environments
#### List Projects
```typescript
const projects = await client.listProjects();
for (const project of projects) {
console.log(`${project.name} (${project.id})`);
}
```
#### Get Project Details
```typescript
const project = await client.getProject('project-id');
console.log(`Project: ${project.name}`);
for (const env of project.environments) {
console.log(` - ${env.name}`);
}
```
#### List Environments
```typescript
const environments = await client.listEnvironments('project-id');
for (const env of environments) {
console.log(env.name);
}
```
### Environment Permissions
Manage who can access secrets in each environment.
#### List Permissions
```typescript
const permissions = await client.listPermissions('project-id', 'production');
for (const perm of permissions) {
console.log(`${perm.user_email}: ${perm.role}`);
}
```
#### Set Permission
```typescript
// Grant write access to a user
await client.setPermission('project-id', 'production', 'user-id', 'write');
```
#### Delete Permission
```typescript
await client.deletePermission('project-id', 'production', 'user-id');
```
#### Get My Permissions
```typescript
const { permissions, is_team_admin } = await client.getMyPermissions('project-id');
for (const perm of permissions) {
console.log(`${perm.environment_name}: ${perm.role} (can_write: ${perm.can_write})`);
}
```
#### Bulk Set Permissions
```typescript
await client.bulkSetPermissions('project-id', 'production', [
{ userId: 'user-1', role: 'write' },
{ userId: 'user-2', role: 'read' },
]);
```
#### Project Defaults
```typescript
// Get default permissions
const defaults = await client.getProjectDefaults('project-id');
// Set default permissions for new team members
await client.setProjectDefaults('project-id', [
{ environmentName: 'development', defaultRole: 'write' },
{ environmentName: 'staging', defaultRole: 'read' },
{ environmentName: 'production', defaultRole: 'none' },
]);
```
### Error Handling
```typescript
import { KeyEnv, KeyEnvError } from '@keyenv/node';
try {
await client.getSecret('project-id', 'production', 'MISSING_KEY');
} catch (error) {
if (error instanceof KeyEnvError) {
console.error(`Error ${error.status}: ${error.message}`);
if (error.status === 401) {
console.error('Invalid or expired token');
} else if (error.status === 403) {
console.error('Access denied');
} else if (error.status === 404) {
console.error('Secret not found');
}
}
}
```
### TypeScript Types
The SDK exports all types for TypeScript users:
```typescript
import type {
Secret,
SecretWithValue,
Project,
Environment,
BulkImportResult
} from '@keyenv/node';
```
### API Reference
#### Constructor Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `token` | `string` | Yes | - | Service token |
| `timeout` | `number` | No | `30000` | Request timeout (ms) |
#### Methods
| Method | Description |
|--------|-------------|
| `getCurrentUser()` | Get current user/token info |
| `listProjects()` | List all accessible projects |
| `getProject(id)` | Get project with environments |
| `listEnvironments(projectId)` | List environments in a project |
| `listSecrets(projectId, env)` | List secret keys (no values) |
| `exportSecrets(projectId, env)` | Export secrets with values |
| `exportSecretsAsObject(projectId, env)` | Export as key-value object |
| `getSecret(projectId, env, key)` | Get single secret |
| `setSecret(projectId, env, key, value)` | Create or update secret |
| `deleteSecret(projectId, env, key)` | Delete secret |
| `bulkImport(projectId, env, secrets)` | Bulk import secrets |
| `loadEnv(projectId, env)` | Load secrets into process.env |
| `generateEnvFile(projectId, env)` | Generate .env file content |
| `listPermissions(projectId, env)` | List permissions for an environment |
| `setPermission(projectId, env, userId, role)` | Set user's permission |
| `deletePermission(projectId, env, userId)` | Delete user's permission |
| `bulkSetPermissions(projectId, env, permissions)` | Bulk set permissions |
| `getMyPermissions(projectId)` | Get current user's permissions |
| `getProjectDefaults(projectId)` | Get default permissions |
| `setProjectDefaults(projectId, defaults)` | Set default permissions |
### Examples
#### Express.js Application
```typescript
import express from 'express';
import { KeyEnv } from '@keyenv/node';
async function main() {
// Load secrets before starting server
const client = new KeyEnv({ token: process.env.KEYENV_TOKEN! });
await client.loadEnv(process.env.KEYENV_PROJECT!, 'production');
const app = express();
app.get('/', (req, res) => {
res.json({ status: 'ok' });
});
app.listen(process.env.PORT || 3000);
}
main();
```
#### Next.js API Route
```typescript
// pages/api/config.ts
import { KeyEnv } from '@keyenv/node';
let secretsLoaded = false;
export default async function handler(req, res) {
if (!secretsLoaded) {
const client = new KeyEnv({ token: process.env.KEYENV_TOKEN! });
await client.loadEnv(process.env.KEYENV_PROJECT!, 'production');
secretsLoaded = true;
}
res.json({
apiUrl: process.env.API_URL,
// Don't expose sensitive secrets!
});
}
```
## Python SDK
Official Python SDK for KeyEnv.
Source: https://keyenv.dev/docs/sdks/python/
Official Python SDK for KeyEnv with full type annotations.
### Installation
```bash
pip install keyenv
```
Or with poetry:
```bash
poetry add keyenv
```
### Quick Start
```python
from keyenv import KeyEnv
import os
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
# Load secrets into os.environ
client.load_env("your-project-id", "production")
print(os.environ["DATABASE_URL"])
```
### Initialize the Client
```python
from keyenv import KeyEnv
client = KeyEnv(
token="your-service-token",
timeout=30.0, # optional, default 30s
)
```
#### Context Manager
Use as a context manager for automatic cleanup:
```python
with KeyEnv(token="your-token") as client:
secrets = client.export_secrets("project-id", "production")
```
### Loading Secrets
#### Load into os.environ
The simplest way to use secrets in your application:
```python
count = client.load_env("project-id", "production")
print(f"Loaded {count} secrets")
# Now use them
print(os.environ["DATABASE_URL"])
print(os.environ["API_KEY"])
```
#### Export as Dictionary
Get secrets as a key-value dictionary:
```python
env = client.export_secrets_as_dict("project-id", "production")
print(env["DATABASE_URL"])
print(env["API_KEY"])
```
#### Export as List
Get secrets with metadata:
```python
secrets = client.export_secrets("project-id", "production")
for secret in secrets:
print(f"{secret.key}={secret.value}")
```
### Managing Secrets
#### Get a Single Secret
```python
secret = client.get_secret("project-id", "production", "DATABASE_URL")
print(secret.value)
print(secret.description)
```
#### Set a Secret
Creates or updates a secret:
```python
client.set_secret("project-id", "production", "API_KEY", "sk_live_...")
# With description
client.set_secret(
"project-id",
"production",
"API_KEY",
"sk_live_...",
description="Production API key"
)
```
#### Delete a Secret
```python
client.delete_secret("project-id", "production", "OLD_KEY")
```
### Bulk Operations
#### Bulk Import
Import multiple secrets at once:
```python
from keyenv import BulkSecretItem
result = client.bulk_import(
"project-id",
"development",
[
BulkSecretItem(key="DATABASE_URL", value="postgres://localhost/mydb"),
BulkSecretItem(key="REDIS_URL", value="redis://localhost:6379"),
{"key": "API_KEY", "value": "sk_test_..."}, # Also accepts dicts
],
overwrite=True,
)
print(f"Created: {result.created}, Updated: {result.updated}")
```
#### Generate .env File
```python
env_content = client.generate_env_file("project-id", "production")
with open(".env", "w") as f:
f.write(env_content)
```
### Projects & Environments
#### List Projects
```python
projects = client.list_projects()
for project in projects:
print(f"{project.name} ({project.id})")
```
#### Get Project Details
```python
project = client.get_project("project-id")
print(f"Project: {project.name}")
for env in project.environments:
print(f" - {env.name}")
```
#### List Environments
```python
environments = client.list_environments("project-id")
for env in environments:
print(env.name)
```
### Environment Permissions
Manage who can access secrets in each environment.
#### List Permissions
```python
permissions = client.list_permissions("project-id", "production")
for perm in permissions:
print(f"{perm.user_email}: {perm.role}")
```
#### Set Permission
```python
# Grant write access to a user
client.set_permission("project-id", "production", "user-id", "write")
```
#### Delete Permission
```python
client.delete_permission("project-id", "production", "user-id")
```
#### Get My Permissions
```python
permissions, is_team_admin = client.get_my_permissions("project-id")
for perm in permissions:
print(f"{perm.environment_name}: {perm.role} (can_write: {perm.can_write})")
```
#### Bulk Set Permissions
```python
client.bulk_set_permissions("project-id", "production", [
{"user_id": "user-1", "role": "write"},
{"user_id": "user-2", "role": "read"},
])
```
#### Project Defaults
```python
# Get default permissions
defaults = client.get_project_defaults("project-id")
# Set default permissions for new team members
client.set_project_defaults("project-id", [
{"environment_name": "development", "default_role": "write"},
{"environment_name": "staging", "default_role": "read"},
{"environment_name": "production", "default_role": "none"},
])
```
### Error Handling
```python
from keyenv import KeyEnv, KeyEnvError
try:
secret = client.get_secret("project-id", "production", "MISSING_KEY")
except KeyEnvError as e:
print(f"Error {e.status}: {e.message}")
if e.status == 401:
print("Invalid or expired token")
elif e.status == 403:
print("Access denied")
elif e.status == 404:
print("Secret not found")
```
### Type Hints
The SDK includes full type annotations for better IDE support:
```python
from keyenv import Secret, SecretWithValue, Project, Environment
```
### API Reference
#### Constructor Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `token` | `str` | Yes | - | Service token |
| `timeout` | `float` | No | `30.0` | Request timeout (seconds) |
#### Methods
| Method | Description |
|--------|-------------|
| `get_current_user()` | Get current user/token info |
| `list_projects()` | List all accessible projects |
| `get_project(id)` | Get project with environments |
| `list_environments(project_id)` | List environments in a project |
| `list_secrets(project_id, env)` | List secret keys (no values) |
| `export_secrets(project_id, env)` | Export secrets with values |
| `export_secrets_as_dict(project_id, env)` | Export as dictionary |
| `get_secret(project_id, env, key)` | Get single secret |
| `set_secret(project_id, env, key, value)` | Create or update secret |
| `delete_secret(project_id, env, key)` | Delete secret |
| `bulk_import(project_id, env, secrets)` | Bulk import secrets |
| `load_env(project_id, env)` | Load secrets into os.environ |
| `generate_env_file(project_id, env)` | Generate .env file content |
| `list_permissions(project_id, env)` | List permissions for an environment |
| `set_permission(project_id, env, user_id, role)` | Set user's permission |
| `delete_permission(project_id, env, user_id)` | Delete user's permission |
| `bulk_set_permissions(project_id, env, permissions)` | Bulk set permissions |
| `get_my_permissions(project_id)` | Get current user's permissions |
| `get_project_defaults(project_id)` | Get default permissions |
| `set_project_defaults(project_id, defaults)` | Set default permissions |
### Examples
#### FastAPI Application
```python
from fastapi import FastAPI
from keyenv import KeyEnv
import os
# Load secrets at startup
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], "production")
app = FastAPI()
@app.get("/")
async def root():
return {"status": "ok"}
@app.get("/config")
async def config():
return {
"api_url": os.environ.get("API_URL"),
# Don't expose sensitive secrets!
}
```
#### Django Settings
```python
# settings.py
from keyenv import KeyEnv
import os
# Load secrets before Django initializes
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], os.environ.get("ENV", "development"))
# Now use secrets in settings
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"HOST": os.environ.get("DB_HOST"),
"NAME": os.environ.get("DB_NAME"),
"USER": os.environ.get("DB_USER"),
"PASSWORD": os.environ.get("DB_PASSWORD"),
}
}
SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY")
```
#### Flask Application
```python
from flask import Flask
from keyenv import KeyEnv
import os
# Load secrets
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], "production")
app = Flask(__name__)
app.config["SECRET_KEY"] = os.environ["FLASK_SECRET_KEY"]
@app.route("/")
def hello():
return {"status": "ok"}
```
#### Script/CLI Tool
```python
#!/usr/bin/env python3
import argparse
from keyenv import KeyEnv
import os
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--env", default="development")
args = parser.parse_args()
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
secrets = client.export_secrets_as_dict("my-project", args.env)
print(f"Database: {secrets['DATABASE_URL']}")
# Do something with secrets...
if __name__ == "__main__":
main()
```
## Go SDK
Official Go SDK for KeyEnv.
Source: https://keyenv.dev/docs/sdks/go/
Official Go SDK for KeyEnv with full type safety.
### Installation
```bash
go get github.com/keyenv/go-sdk
```
### Quick Start
```go
package main
import (
"context"
"fmt"
"os"
"github.com/keyenv/go-sdk"
)
func main() {
client, err := keyenv.New(keyenv.Config{
Token: os.Getenv("KEYENV_TOKEN"),
})
if err != nil {
panic(err)
}
ctx := context.Background()
// Load secrets into environment
if _, err := client.LoadEnv(ctx, "your-project-id", "production"); err != nil {
panic(err)
}
fmt.Println(os.Getenv("DATABASE_URL"))
}
```
### Initialize the Client
```go
client, err := keyenv.New(keyenv.Config{
Token: "your-service-token",
Timeout: 30 * time.Second, // optional, default 30s
CacheTTL: 5 * time.Minute, // optional, default disabled
})
```
### Loading Secrets
#### Load into Environment
The simplest way to use secrets in your application:
```go
ctx := context.Background()
count, err := client.LoadEnv(ctx, "project-id", "production")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Loaded %d secrets\n", count)
// Now use them
fmt.Println(os.Getenv("DATABASE_URL"))
```
#### Export as Map
Get secrets as a map:
```go
secrets, err := client.ExportSecretsAsMap(ctx, "project-id", "production")
if err != nil {
log.Fatal(err)
}
fmt.Println(secrets["DATABASE_URL"])
```
#### Export with Metadata
Get secrets with full metadata:
```go
secrets, err := client.ExportSecrets(ctx, "project-id", "production")
if err != nil {
log.Fatal(err)
}
for _, secret := range secrets {
fmt.Printf("%s=%s\n", secret.Key, secret.Value)
}
```
### Managing Secrets
#### Get a Single Secret
```go
secret, err := client.GetSecret(ctx, "project-id", "production", "DATABASE_URL")
if err != nil {
log.Fatal(err)
}
fmt.Println(secret.Value)
```
#### Set a Secret
Creates or updates a secret:
```go
err := client.SetSecret(ctx, "project-id", "production", "API_KEY", "sk_live_...")
if err != nil {
log.Fatal(err)
}
// With description
description := "Production API key"
err = client.SetSecretWithDescription(ctx, "project-id", "production", "API_KEY", "sk_live_...", &description)
```
#### Delete a Secret
```go
err := client.DeleteSecret(ctx, "project-id", "production", "OLD_KEY")
```
### Bulk Operations
#### Bulk Import
```go
result, err := client.BulkImport(ctx, "project-id", "development", []keyenv.SecretInput{
{Key: "DATABASE_URL", Value: "postgres://localhost/mydb"},
{Key: "REDIS_URL", Value: "redis://localhost:6379"},
}, keyenv.BulkImportOptions{Overwrite: true})
fmt.Printf("Created: %d, Updated: %d\n", result.Created, result.Updated)
```
#### Generate .env File
```go
content, err := client.GenerateEnvFile(ctx, "project-id", "production")
if err != nil {
log.Fatal(err)
}
os.WriteFile(".env", []byte(content), 0644)
```
### Projects & Environments
#### List Projects
```go
projects, err := client.ListProjects(ctx)
for _, project := range projects {
fmt.Printf("%s (%s)\n", project.Name, project.ID)
}
```
#### Get Project Details
```go
project, err := client.GetProject(ctx, "project-id")
fmt.Printf("Project: %s\n", project.Name)
for _, env := range project.Environments {
fmt.Printf(" - %s\n", env.Name)
}
```
### Environment Permissions
Manage who can access secrets in each environment.
#### List Permissions
```go
permissions, err := client.ListPermissions(ctx, "project-id", "production")
if err != nil {
log.Fatal(err)
}
for _, perm := range permissions {
fmt.Printf("%s: %s\n", perm.UserEmail, perm.Role)
}
```
#### Set Permission
```go
// Grant write access to a user
err := client.SetPermission(ctx, "project-id", "production", "user-id", "write")
if err != nil {
log.Fatal(err)
}
```
#### Delete Permission
```go
err := client.DeletePermission(ctx, "project-id", "production", "user-id")
```
#### Get My Permissions
```go
result, err := client.GetMyPermissions(ctx, "project-id")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Is team admin: %v\n", result.IsTeamAdmin)
for _, perm := range result.Permissions {
fmt.Printf("%s: %s (can_write: %v)\n", perm.EnvironmentName, perm.Role, perm.CanWrite)
}
```
#### Bulk Set Permissions
```go
err := client.BulkSetPermissions(ctx, "project-id", "production", []keyenv.PermissionInput{
{UserID: "user-1", Role: "write"},
{UserID: "user-2", Role: "read"},
})
```
#### Project Defaults
```go
// Get default permissions
defaults, err := client.GetProjectDefaults(ctx, "project-id")
for _, d := range defaults {
fmt.Printf("%s: %s\n", d.EnvironmentName, d.DefaultRole)
}
// Set default permissions for new team members
err = client.SetProjectDefaults(ctx, "project-id", []keyenv.ProjectDefaultInput{
{EnvironmentName: "development", DefaultRole: "write"},
{EnvironmentName: "staging", DefaultRole: "read"},
{EnvironmentName: "production", DefaultRole: "none"},
})
```
### Error Handling
```go
secret, err := client.GetSecret(ctx, "project-id", "production", "MISSING_KEY")
if err != nil {
var keyenvErr *keyenv.Error
if errors.As(err, &keyenvErr) {
switch keyenvErr.Status {
case 401:
log.Fatal("Invalid or expired token")
case 403:
log.Fatal("Access denied")
case 404:
log.Fatal("Secret not found")
default:
log.Fatalf("Error %d: %s", keyenvErr.Status, keyenvErr.Message)
}
}
}
```
### Caching
Enable caching for better performance in serverless environments:
```go
client, _ := keyenv.New(keyenv.Config{
Token: os.Getenv("KEYENV_TOKEN"),
CacheTTL: 5 * time.Minute,
})
ctx := context.Background()
// Cached for 5 minutes
secrets, _ := client.ExportSecrets(ctx, "project-id", "production")
// Clear cache manually
client.ClearCache("project-id", "production")
```
### API Reference
#### Constructor Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `Token` | `string` | Yes | - | Service token |
| `Timeout` | `time.Duration` | No | `30s` | Request timeout |
| `CacheTTL` | `time.Duration` | No | `0` | Cache TTL (0 = disabled) |
#### Methods
All methods require a `context.Context` as the first parameter.
| Method | Description |
|--------|-------------|
| `GetCurrentUser(ctx)` | Get current user/token info |
| `ListProjects(ctx)` | List all accessible projects |
| `GetProject(ctx, id)` | Get project with environments |
| `ListEnvironments(ctx, projectId)` | List environments |
| `ListSecrets(ctx, projectId, env)` | List secret keys (no values) |
| `ExportSecrets(ctx, projectId, env)` | Export secrets with values |
| `ExportSecretsAsMap(ctx, projectId, env)` | Export as map |
| `GetSecret(ctx, projectId, env, key)` | Get single secret |
| `SetSecret(ctx, projectId, env, key, value)` | Create or update secret |
| `DeleteSecret(ctx, projectId, env, key)` | Delete secret |
| `BulkImport(ctx, projectId, env, secrets, opts)` | Bulk import secrets |
| `LoadEnv(ctx, projectId, env)` | Load secrets into os.Environ |
| `GenerateEnvFile(ctx, projectId, env)` | Generate .env file content |
| `ClearCache(projectId, env)` | Clear cached secrets (no ctx) |
| `ListPermissions(ctx, projectId, env)` | List environment permissions |
| `SetPermission(ctx, projectId, env, userId, role)` | Set user permission |
| `DeletePermission(ctx, projectId, env, userId)` | Remove user permission |
| `GetMyPermissions(ctx, projectId)` | Get current user's permissions |
| `BulkSetPermissions(ctx, projectId, env, perms)` | Bulk set permissions |
| `GetProjectDefaults(ctx, projectId)` | Get default permissions |
| `SetProjectDefaults(ctx, projectId, defaults)` | Set default permissions |
### Examples
#### HTTP Server
```go
package main
import (
"context"
"log"
"net/http"
"os"
"github.com/keyenv/go-sdk"
)
func main() {
client, _ := keyenv.New(keyenv.Config{
Token: os.Getenv("KEYENV_TOKEN"),
})
// Load secrets before starting server
client.LoadEnv(context.Background(), os.Getenv("KEYENV_PROJECT"), "production")
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("OK"))
})
log.Fatal(http.ListenAndServe(":"+os.Getenv("PORT"), nil))
}
```
#### Lambda Function
```go
package main
import (
"context"
"os"
"time"
"github.com/aws/aws-lambda-go/lambda"
"github.com/keyenv/go-sdk"
)
var client *keyenv.Client
func init() {
client, _ = keyenv.New(keyenv.Config{
Token: os.Getenv("KEYENV_TOKEN"),
CacheTTL: 5 * time.Minute, // Cache across warm invocations
})
client.LoadEnv(context.Background(), os.Getenv("KEYENV_PROJECT"), "production")
}
func handler(ctx context.Context) (string, error) {
return os.Getenv("API_KEY"), nil
}
func main() {
lambda.Start(handler)
}
```
## Rust SDK
Official Rust SDK for KeyEnv.
Source: https://keyenv.dev/docs/sdks/rust/
Official Rust SDK for KeyEnv with async/await support.
### Installation
Add to your `Cargo.toml`:
```toml
[dependencies]
keyenv = "1.2"
tokio = { version = "1", features = ["full"] }
```
Or using cargo:
```bash
cargo add keyenv tokio --features tokio/full
```
### Quick Start
```rust
use keyenv::KeyEnv;
use std::env;
#[tokio::main]
async fn main() -> Result<(), keyenv::Error> {
let client = KeyEnv::builder()
.token(env::var("KEYENV_TOKEN").expect("KEYENV_TOKEN not set"))
.build()?;
// Load secrets into environment
client.load_env("your-project-id", "production").await?;
println!("{}", env::var("DATABASE_URL").unwrap());
Ok(())
}
```
### Initialize the Client
```rust
use keyenv::KeyEnv;
use std::time::Duration;
let client = KeyEnv::builder()
.token("your-service-token")
.timeout(Duration::from_secs(30)) // optional
.cache_ttl(Duration::from_secs(300)) // optional
.build()?;
```
### Loading Secrets
#### Load into Environment
The simplest way to use secrets in your application:
```rust
let count = client.load_env("project-id", "production").await?;
println!("Loaded {} secrets", count);
// Now use them
println!("{}", env::var("DATABASE_URL").unwrap());
```
#### Export as HashMap
Get secrets as a HashMap:
```rust
let secrets = client.export_secrets_as_map("project-id", "production").await?;
println!("{}", secrets.get("DATABASE_URL").unwrap());
```
#### Export with Metadata
Get secrets with full metadata:
```rust
let secrets = client.export_secrets("project-id", "production").await?;
for secret in secrets {
println!("{}={}", secret.key, secret.value);
}
```
### Managing Secrets
#### Get a Single Secret
```rust
let secret = client.get_secret("project-id", "production", "DATABASE_URL").await?;
println!("{}", secret.value);
```
#### Set a Secret
Creates or updates a secret:
```rust
client.set_secret("project-id", "production", "API_KEY", "sk_live_...").await?;
// With description
client.set_secret_with_description(
"project-id",
"production",
"API_KEY",
"sk_live_...",
"Production API key"
).await?;
```
#### Delete a Secret
```rust
client.delete_secret("project-id", "production", "OLD_KEY").await?;
```
### Bulk Operations
#### Bulk Import
```rust
use keyenv::{SecretInput, BulkImportOptions};
let result = client.bulk_import(
"project-id",
"development",
vec![
SecretInput::new("DATABASE_URL", "postgres://localhost/mydb"),
SecretInput::new("REDIS_URL", "redis://localhost:6379"),
],
BulkImportOptions { overwrite: true },
).await?;
println!("Created: {}, Updated: {}", result.created, result.updated);
```
#### Generate .env File
```rust
use std::fs;
let content = client.generate_env_file("project-id", "production").await?;
fs::write(".env", content)?;
```
### Projects & Environments
#### List Projects
```rust
let projects = client.list_projects().await?;
for project in projects {
println!("{} ({})", project.name, project.id);
}
```
#### Get Project Details
```rust
let project = client.get_project("project-id").await?;
println!("Project: {}", project.name);
for env in project.environments {
println!(" - {}", env.name);
}
```
### Error Handling
```rust
use keyenv::{KeyEnv, Error};
match client.get_secret("project-id", "production", "MISSING_KEY").await {
Ok(secret) => println!("{}", secret.value),
Err(Error::Api { status, message, .. }) => {
match status {
401 => eprintln!("Invalid or expired token"),
403 => eprintln!("Access denied"),
404 => eprintln!("Secret not found"),
_ => eprintln!("Error {}: {}", status, message),
}
}
Err(e) => eprintln!("Error: {}", e),
}
```
### Caching
Enable caching for better performance:
```rust
let client = KeyEnv::builder()
.token(env::var("KEYENV_TOKEN")?)
.cache_ttl(Duration::from_secs(300)) // 5 minutes
.build()?;
// Cached for 5 minutes
let secrets = client.export_secrets("project-id", "production").await?;
// Clear cache manually
client.clear_cache(Some("project-id"), Some("production"));
```
### API Reference
#### Builder Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `token` | `String` | Yes | - | Service token |
| `timeout` | `Duration` | No | `30s` | Request timeout |
| `cache_ttl` | `Duration` | No | `0` | Cache TTL (0 = disabled) |
#### Methods
| Method | Description |
|--------|-------------|
| `get_current_user()` | Get current user/token info |
| `list_projects()` | List all accessible projects |
| `get_project(id)` | Get project with environments |
| `list_environments(project_id)` | List environments |
| `list_secrets(project_id, env)` | List secret keys (no values) |
| `export_secrets(project_id, env)` | Export secrets with values |
| `export_secrets_as_map(project_id, env)` | Export as HashMap |
| `get_secret(project_id, env, key)` | Get single secret |
| `set_secret(project_id, env, key, value)` | Create or update secret |
| `delete_secret(project_id, env, key)` | Delete secret |
| `bulk_import(project_id, env, secrets)` | Bulk import secrets |
| `load_env(project_id, env)` | Load secrets into env vars |
| `generate_env_file(project_id, env)` | Generate .env file content |
| `clear_cache(project_id, env)` | Clear cached secrets |
### Examples
#### Actix Web Server
```rust
use actix_web::{web, App, HttpServer, Responder};
use keyenv::KeyEnv;
use std::env;
async fn index() -> impl Responder {
"OK"
}
#[actix_web::main]
async fn main() -> std::io::Result<()> {
let client = KeyEnv::builder()
.token(env::var("KEYENV_TOKEN").unwrap())
.build()
.unwrap();
// Load secrets before starting server
client.load_env(
&env::var("KEYENV_PROJECT").unwrap(),
"production"
).await.unwrap();
HttpServer::new(|| {
App::new().route("/", web::get().to(index))
})
.bind(("0.0.0.0", 8080))?
.run()
.await
}
```
#### Lambda Function
```rust
use keyenv::KeyEnv;
use lambda_runtime::{service_fn, LambdaEvent, Error};
use once_cell::sync::Lazy;
use std::env;
static CLIENT: Lazy = Lazy::new(|| {
KeyEnv::builder()
.token(env::var("KEYENV_TOKEN").unwrap())
.cache_ttl(std::time::Duration::from_secs(300))
.build()
.unwrap()
});
async fn handler(_event: LambdaEvent<()>) -> Result {
CLIENT.load_env(&env::var("KEYENV_PROJECT")?, "production").await?;
Ok(env::var("API_KEY")?)
}
#[tokio::main]
async fn main() -> Result<(), Error> {
lambda_runtime::run(service_fn(handler)).await
}
```
## Java SDK
Official Java SDK for KeyEnv.
Source: https://keyenv.dev/docs/sdks/java/
Official Java SDK for KeyEnv with Java 11+ support and async/await patterns.
> **Warning**
>
> **Beta Release**: This SDK is currently in development. APIs may change before the stable 1.0 release.
### Installation
#### Maven
Add the JitPack repository and dependency to your `pom.xml`:
```xml
jitpack.iohttps://jitpack.iocom.github.keyenvjava-sdkv1.1.0
```
#### Gradle
Add the JitPack repository and dependency to your `build.gradle`:
```groovy
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.keyenv:java-sdk:v1.1.0'
}
```
Or with Kotlin DSL (`build.gradle.kts`):
```kotlin
repositories {
maven("https://jitpack.io")
}
dependencies {
implementation("com.github.keyenv:java-sdk:v1.1.0")
}
```
### Quick Start
```java
import dev.keyenv.KeyEnv;
public class Application {
public static void main(String[] args) {
KeyEnv client = KeyEnv.create(System.getenv("KEYENV_TOKEN"));
// Load secrets into system properties
int count = client.loadEnv("your-project-id", "production");
System.out.println("Loaded " + count + " secrets");
// Access secrets via System.getProperty
System.out.println(System.getProperty("DATABASE_URL"));
}
}
```
### Initialize the Client
#### Simple Initialization
```java
import dev.keyenv.KeyEnv;
KeyEnv client = KeyEnv.create(System.getenv("KEYENV_TOKEN"));
```
#### Builder Pattern
For more control, use the builder:
```java
import dev.keyenv.KeyEnv;
import java.time.Duration;
KeyEnv client = KeyEnv.builder()
.token(System.getenv("KEYENV_TOKEN"))
.timeout(Duration.ofSeconds(60))
.cacheTtl(Duration.ofMinutes(5))
.build();
```
### Loading Secrets
#### Load into System Properties
The simplest way to use secrets in your application:
```java
int count = client.loadEnv("project-id", "production");
System.out.println("Loaded " + count + " secrets");
// Access via System.getProperty
String dbUrl = System.getProperty("DATABASE_URL");
String apiKey = System.getProperty("API_KEY");
```
#### Get Secrets as Map
Get secrets as a key-value map:
```java
import java.util.Map;
Map secrets = client.exportSecretsAsMap("project-id", "production");
System.out.println(secrets.get("DATABASE_URL"));
System.out.println(secrets.get("API_KEY"));
```
#### Export as List
Get secrets with metadata:
```java
import dev.keyenv.types.SecretWithValueAndInheritance;
import java.util.List;
List secrets = client.exportSecrets("project-id", "production");
for (SecretWithValueAndInheritance secret : secrets) {
System.out.println(secret.getKey() + "=" + secret.getValue());
}
```
### Managing Secrets
#### Get a Single Secret
```java
import dev.keyenv.types.SecretWithValue;
SecretWithValue secret = client.getSecret("project-id", "production", "DATABASE_URL");
System.out.println(secret.getValue());
System.out.println(secret.getDescription());
```
#### Set a Secret
Creates or updates a secret:
```java
client.setSecret("project-id", "production", "API_KEY", "sk_live_...");
// With description
client.setSecret("project-id", "production", "API_KEY", "sk_live_...", "Production API key");
```
#### Delete a Secret
```java
client.deleteSecret("project-id", "production", "OLD_KEY");
```
### Bulk Operations
#### Bulk Import
Import multiple secrets at once:
```java
import dev.keyenv.types.SecretInput;
import dev.keyenv.types.BulkImportOptions;
import dev.keyenv.types.BulkImportResult;
import java.util.List;
List secrets = List.of(
new SecretInput("DATABASE_URL", "postgres://localhost/mydb", null),
new SecretInput("REDIS_URL", "redis://localhost:6379", null),
new SecretInput("API_KEY", "sk_test_...", "Test API key")
);
BulkImportResult result = client.bulkImport(
"project-id",
"development",
secrets,
new BulkImportOptions(true) // overwrite existing
);
System.out.println("Created: " + result.getCreated() + ", Updated: " + result.getUpdated());
```
#### Generate .env File
```java
import java.nio.file.Files;
import java.nio.file.Paths;
String envContent = client.generateEnvFile("project-id", "production");
Files.writeString(Paths.get(".env"), envContent);
```
### Projects & Environments
#### List Projects
```java
import dev.keyenv.types.Project;
import java.util.List;
List projects = client.listProjects();
for (Project project : projects) {
System.out.println(project.getName() + " (" + project.getId() + ")");
}
```
#### Get Project Details
```java
import dev.keyenv.types.Project;
Project project = client.getProject("project-id");
System.out.println("Project: " + project.getName());
for (var env : project.getEnvironments()) {
System.out.println(" - " + env.getName());
}
```
#### List Environments
```java
import dev.keyenv.types.Environment;
import java.util.List;
List environments = client.listEnvironments("project-id");
for (Environment env : environments) {
System.out.println(env.getName());
}
```
### Async Operations
All methods have async variants that return `CompletableFuture`:
```java
import java.util.concurrent.CompletableFuture;
// Async secret loading
CompletableFuture future = client.loadEnvAsync("project-id", "production");
future.thenAccept(count -> {
System.out.println("Loaded " + count + " secrets");
});
// Async secrets retrieval
client.exportSecretsAsMapAsync("project-id", "production")
.thenAccept(secrets -> {
System.out.println(secrets.get("DATABASE_URL"));
});
```
### Caching
Enable caching for better performance in high-throughput applications:
```java
import java.time.Duration;
KeyEnv client = KeyEnv.builder()
.token(System.getenv("KEYENV_TOKEN"))
.cacheTtl(Duration.ofMinutes(5))
.build();
// First call fetches from API
client.exportSecrets("project-id", "production");
// Subsequent calls within TTL use cache
client.exportSecrets("project-id", "production");
// Clear cache when needed
client.clearCache("project-id", "production");
client.clearAllCache();
```
### Error Handling
```java
import dev.keyenv.KeyEnv;
import dev.keyenv.KeyEnvException;
try {
var secret = client.getSecret("project-id", "production", "MISSING_KEY");
} catch (KeyEnvException e) {
System.err.println("Error " + e.getStatus() + ": " + e.getMessage());
if (e.getStatus() == 401) {
System.err.println("Invalid or expired token");
} else if (e.getStatus() == 403) {
System.err.println("Access denied");
} else if (e.getStatus() == 404) {
System.err.println("Secret not found");
}
}
```
### API Reference
#### Constructor Options (Builder)
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `token` | `String` | Yes | - | Service token |
| `timeout` | `Duration` | No | `30s` | Request timeout |
| `cacheTtl` | `Duration` | No | `0` | Cache TTL (0 disables) |
| `baseUrl` | `String` | No | `https://api.keyenv.dev` | API base URL |
#### Methods
| Method | Description |
|--------|-------------|
| `getCurrentUser()` | Get current user/token info |
| `listProjects()` | List all accessible projects |
| `getProject(id)` | Get project with environments |
| `listEnvironments(projectId)` | List environments in a project |
| `listSecrets(projectId, env)` | List secret keys (no values) |
| `exportSecrets(projectId, env)` | Export secrets with values |
| `exportSecretsAsMap(projectId, env)` | Export as key-value map |
| `getSecret(projectId, env, key)` | Get single secret |
| `setSecret(projectId, env, key, value)` | Create or update secret |
| `deleteSecret(projectId, env, key)` | Delete secret |
| `bulkImport(projectId, env, secrets, options)` | Bulk import secrets |
| `loadEnv(projectId, env)` | Load secrets into System properties |
| `generateEnvFile(projectId, env)` | Generate .env file content |
| `listPermissions(projectId, env)` | List permissions for an environment |
| `setPermission(projectId, env, userId, role)` | Set user's permission |
| `deletePermission(projectId, env, userId)` | Delete user's permission |
| `getMyPermissions(projectId)` | Get current user's permissions |
| `getProjectDefaults(projectId)` | Get default permissions |
| `setProjectDefaults(projectId, defaults)` | Set default permissions |
### Examples
#### Spring Boot Application
```java
import dev.keyenv.KeyEnv;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import jakarta.annotation.PostConstruct;
@SpringBootApplication
public class Application {
@PostConstruct
public void loadSecrets() {
String token = System.getenv("KEYENV_TOKEN");
if (token != null) {
KeyEnv client = KeyEnv.create(token);
client.loadEnv(System.getenv("KEYENV_PROJECT"), "production");
}
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
#### Micronaut Application
```java
import dev.keyenv.KeyEnv;
import io.micronaut.context.event.ApplicationEventListener;
import io.micronaut.context.event.StartupEvent;
import jakarta.inject.Singleton;
@Singleton
public class SecretsLoader implements ApplicationEventListener {
@Override
public void onApplicationEvent(StartupEvent event) {
String token = System.getenv("KEYENV_TOKEN");
if (token != null) {
KeyEnv client = KeyEnv.create(token);
int count = client.loadEnv(System.getenv("KEYENV_PROJECT"), "production");
System.out.println("Loaded " + count + " secrets from KeyEnv");
}
}
}
```
#### Quarkus Application
```java
import dev.keyenv.KeyEnv;
import io.quarkus.runtime.Startup;
import jakarta.annotation.PostConstruct;
import jakarta.enterprise.context.ApplicationScoped;
@ApplicationScoped
@Startup
public class SecretsConfig {
@PostConstruct
void loadSecrets() {
String token = System.getenv("KEYENV_TOKEN");
if (token != null) {
KeyEnv client = KeyEnv.create(token);
client.loadEnv(System.getenv("KEYENV_PROJECT"), "production");
}
}
}
```
## PHP SDK
Official PHP SDK for KeyEnv.
Source: https://keyenv.dev/docs/sdks/php/
Official PHP SDK for KeyEnv with PHP 8.0+ support.
> **Warning**
>
> **Beta Release**: This SDK is currently in development. APIs may change before the stable 1.0 release.
### Installation
Install via Composer:
```bash
composer require keyenv/keyenv
```
### Quick Start
```php
loadEnv('your-project-id', 'production');
echo "Loaded {$count} secrets\n";
// Access secrets
echo $_ENV['DATABASE_URL'];
echo getenv('DATABASE_URL');
```
### Initialize the Client
#### Simple Initialization
```php
loadEnv('project-id', 'production');
echo "Loaded {$count} secrets\n";
// Access via $_ENV
echo $_ENV['DATABASE_URL'];
echo $_ENV['API_KEY'];
// Or via getenv()
echo getenv('DATABASE_URL');
echo getenv('API_KEY');
```
#### Get Secrets as Array
Get secrets as a key-value associative array:
```php
exportSecretsAsArray('project-id', 'production');
echo $secrets['DATABASE_URL'];
echo $secrets['API_KEY'];
```
#### Export as List
Get secrets with metadata:
```php
exportSecrets('project-id', 'production');
foreach ($secrets as $secret) {
echo "{$secret->key}={$secret->value}\n";
}
```
### Managing Secrets
#### Get a Single Secret
```php
getSecret('project-id', 'production', 'DATABASE_URL');
echo $secret->value;
echo $secret->description;
```
#### Set a Secret
Creates or updates a secret:
```php
setSecret('project-id', 'production', 'API_KEY', 'sk_live_...');
// With description
$client->setSecret(
'project-id',
'production',
'API_KEY',
'sk_live_...',
description: 'Production API key'
);
```
#### Create a Secret
Explicitly create a new secret (fails if exists):
```php
createSecret(
'project-id',
'production',
'NEW_KEY',
'new_value',
description: 'New secret'
);
```
#### Update a Secret
Explicitly update an existing secret (fails if not exists):
```php
updateSecret(
'project-id',
'production',
'EXISTING_KEY',
'updated_value'
);
```
#### Delete a Secret
```php
deleteSecret('project-id', 'production', 'OLD_KEY');
```
### Environments
#### List Environments
```php
listEnvironments('project-id');
foreach ($environments as $env) {
echo $env->name . "\n";
}
```
### Generate .env File
```php
generateEnvFile('project-id', 'production');
file_put_contents('.env', $envContent);
```
### Error Handling
```php
getSecret('project-id', 'production', 'MISSING_KEY');
} catch (KeyEnvException $e) {
echo "Error {$e->getCode()}: {$e->getMessage()}\n";
if ($e->isNotFound()) {
echo "Secret not found\n";
} elseif ($e->isUnauthorized()) {
echo "Invalid or expired token\n";
} elseif ($e->isForbidden()) {
echo "Access denied\n";
}
// Access error details
if ($e->getDetails()) {
print_r($e->getDetails());
}
}
```
### API Reference
#### Constructor Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `token` | `string` | Yes | - | Service token |
| `timeout` | `int` | No | `30` | Request timeout (seconds) |
#### Methods
| Method | Description |
|--------|-------------|
| `validateToken()` | Validate token and get user info |
| `listEnvironments(projectId)` | List environments in a project |
| `listSecrets(projectId, env)` | List secret keys (no values) |
| `exportSecrets(projectId, env)` | Export secrets with values |
| `exportSecretsAsArray(projectId, env)` | Export as associative array |
| `getSecret(projectId, env, key)` | Get single secret |
| `createSecret(projectId, env, key, value)` | Create new secret |
| `updateSecret(projectId, env, key, value)` | Update existing secret |
| `setSecret(projectId, env, key, value)` | Create or update secret |
| `deleteSecret(projectId, env, key)` | Delete secret |
| `loadEnv(projectId, env)` | Load secrets into $_ENV |
| `generateEnvFile(projectId, env)` | Generate .env file content |
### Examples
#### Laravel Application
```php
loadEnv(env('KEYENV_PROJECT'), env('APP_ENV', 'production'));
}
```
#### Laravel Service Provider
```php
app->singleton(KeyEnv::class, function () {
return KeyEnv::create(config('services.keyenv.token'));
});
}
public function boot(): void
{
if ($token = config('services.keyenv.token')) {
$client = app(KeyEnv::class);
$client->loadEnv(
config('services.keyenv.project'),
app()->environment()
);
}
}
}
```
#### Symfony Application
```php
['loadSecrets', 255],
];
}
public function loadSecrets(): void
{
static $loaded = false;
if ($loaded) {
return;
}
if ($token = $_ENV['KEYENV_TOKEN'] ?? null) {
$client = KeyEnv::create($token);
$client->loadEnv($_ENV['KEYENV_PROJECT'], $_ENV['APP_ENV'] ?? 'prod');
$loaded = true;
}
}
}
```
#### WordPress Plugin
```php
exportSecretsAsArray(KEYENV_PROJECT, KEYENV_ENV ?? 'production');
foreach ($secrets as $key => $value) {
if (!defined($key)) {
define($key, $value);
}
}
}, 1);
```
#### CLI Script
```php
#!/usr/bin/env php
exportSecrets('my-project', 'production');
foreach ($secrets as $secret) {
echo "{$secret->key}={$secret->value}\n";
}
} catch (KeyEnvException $e) {
fwrite(STDERR, "KeyEnv Error: {$e->getMessage()}\n");
exit(1);
}
```
#### PHPUnit Test Setup
```php
loadEnv(getenv('KEYENV_PROJECT'), 'test');
}
}
}
```
## Ruby SDK
Official Ruby SDK for KeyEnv.
Source: https://keyenv.dev/docs/sdks/ruby/
Official Ruby SDK for KeyEnv with Ruby 3.0+ support.
> **Warning**
>
> **Beta Release**: This SDK is currently in development. APIs may change before the stable 1.0 release.
### Installation
Add to your Gemfile:
```ruby
gem 'keyenv'
```
Then run:
```bash
bundle install
```
Or install directly:
```bash
gem install keyenv
```
### Quick Start
```ruby
require 'keyenv'
client = KeyEnv::Client.new(token: ENV['KEYENV_TOKEN'])
# Load secrets into ENV
count = client.load_env(project_id: 'your-project-id', environment: 'production')
puts "Loaded #{count} secrets"
# Access secrets
puts ENV['DATABASE_URL']
```
### Initialize the Client
#### Simple Initialization
```ruby
require 'keyenv'
client = KeyEnv::Client.new(token: ENV['KEYENV_TOKEN'])
```
#### With Options
```ruby
client = KeyEnv::Client.new(
token: ENV['KEYENV_TOKEN'],
timeout: 60, # Request timeout in seconds (default: 30)
cache_ttl: 300 # Cache TTL in seconds (default: 0 = disabled)
)
```
### Loading Secrets
#### Load into ENV
The simplest way to use secrets in your application:
```ruby
count = client.load_env(project_id: 'project-id', environment: 'production')
puts "Loaded #{count} secrets"
# Access via ENV
puts ENV['DATABASE_URL']
puts ENV['API_KEY']
```
#### Get Secrets as Hash
Get secrets as a key-value hash:
```ruby
secrets = client.export_secrets_as_hash(project_id: 'project-id', environment: 'production')
puts secrets['DATABASE_URL']
puts secrets['API_KEY']
```
#### Export as Array
Get secrets with metadata:
```ruby
secrets = client.export_secrets(project_id: 'project-id', environment: 'production')
secrets.each do |secret|
puts "#{secret.key}=#{secret.value}"
end
```
### Managing Secrets
#### Get a Single Secret
```ruby
secret = client.get_secret(project_id: 'project-id', environment: 'production', key: 'DATABASE_URL')
puts secret.value
puts secret.description
```
#### Set a Secret
Creates or updates a secret:
```ruby
client.set_secret(
project_id: 'project-id',
environment: 'production',
key: 'API_KEY',
value: 'sk_live_...'
)
# With description
client.set_secret(
project_id: 'project-id',
environment: 'production',
key: 'API_KEY',
value: 'sk_live_...',
description: 'Production API key'
)
```
#### Create a Secret
Explicitly create a new secret:
```ruby
secret = client.create_secret(
project_id: 'project-id',
environment: 'production',
key: 'NEW_KEY',
value: 'new_value',
description: 'New secret'
)
```
#### Update a Secret
Explicitly update an existing secret:
```ruby
secret = client.update_secret(
project_id: 'project-id',
environment: 'production',
key: 'EXISTING_KEY',
value: 'updated_value'
)
```
#### Delete a Secret
```ruby
client.delete_secret(project_id: 'project-id', environment: 'production', key: 'OLD_KEY')
```
### Bulk Operations
#### Bulk Import
Import multiple secrets at once:
```ruby
result = client.bulk_import(
project_id: 'project-id',
environment: 'development',
secrets: [
{ key: 'DATABASE_URL', value: 'postgres://localhost/mydb' },
{ key: 'REDIS_URL', value: 'redis://localhost:6379' },
{ key: 'API_KEY', value: 'sk_test_...', description: 'Test API key' }
],
overwrite: true
)
puts "Created: #{result.created}, Updated: #{result.updated}"
```
#### Generate .env File
```ruby
env_content = client.generate_env_file(project_id: 'project-id', environment: 'production')
File.write('.env', env_content)
```
### Projects & Environments
#### List Projects
```ruby
projects = client.list_projects
projects.each do |project|
puts "#{project.name} (#{project.id})"
end
```
#### Get Project Details
```ruby
project = client.get_project(project_id: 'project-id')
puts "Project: #{project.name}"
project.environments.each do |env|
puts " - #{env.name}"
end
```
#### List Environments
```ruby
environments = client.list_environments(project_id: 'project-id')
environments.each do |env|
puts env.name
end
```
### Environment Permissions
#### List Permissions
```ruby
permissions = client.list_permissions(project_id: 'project-id', environment: 'production')
permissions.each do |perm|
puts "#{perm.user_email}: #{perm.role}"
end
```
#### Set Permission
```ruby
client.set_permission(
project_id: 'project-id',
environment: 'production',
user_id: 'user-id',
role: 'write'
)
```
#### Get My Permissions
```ruby
permissions, is_team_admin = client.get_my_permissions(project_id: 'project-id')
permissions.each do |perm|
puts "#{perm.environment_name}: #{perm.role} (can_write: #{perm.can_write})"
end
```
### Caching
Enable caching for better performance in high-throughput applications:
```ruby
client = KeyEnv::Client.new(
token: ENV['KEYENV_TOKEN'],
cache_ttl: 300 # 5 minutes
)
# First call fetches from API
client.export_secrets(project_id: 'project-id', environment: 'production')
# Subsequent calls within TTL use cache
client.export_secrets(project_id: 'project-id', environment: 'production')
# Clear cache when needed
client.clear_cache(project_id: 'project-id', environment: 'production')
client.clear_cache # Clear all
```
### Error Handling
```ruby
require 'keyenv'
begin
secret = client.get_secret(project_id: 'project-id', environment: 'production', key: 'MISSING_KEY')
rescue KeyEnv::AuthenticationError => e
puts "Invalid or expired token: #{e.message}"
rescue KeyEnv::NotFoundError => e
puts "Secret not found: #{e.message}"
rescue KeyEnv::ValidationError => e
puts "Validation error: #{e.message}"
puts "Details: #{e.details}" if e.details
rescue KeyEnv::RateLimitError => e
puts "Rate limited, try again later"
rescue KeyEnv::Error => e
puts "Error #{e.status}: #{e.message}"
end
```
### API Reference
#### Constructor Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `token` | `String` | Yes | - | Service token |
| `timeout` | `Integer` | No | `30` | Request timeout (seconds) |
| `cache_ttl` | `Integer` | No | `0` | Cache TTL (0 disables) |
#### Methods
| Method | Description |
|--------|-------------|
| `get_current_user` | Get current user/token info |
| `validate_token` | Validate token and get user info |
| `list_projects` | List all accessible projects |
| `get_project(project_id:)` | Get project with environments |
| `list_environments(project_id:)` | List environments in a project |
| `list_secrets(project_id:, environment:)` | List secret keys (no values) |
| `export_secrets(project_id:, environment:)` | Export secrets with values |
| `export_secrets_as_hash(project_id:, environment:)` | Export as hash |
| `get_secret(project_id:, environment:, key:)` | Get single secret |
| `create_secret(project_id:, environment:, key:, value:)` | Create new secret |
| `update_secret(project_id:, environment:, key:, value:)` | Update existing secret |
| `set_secret(project_id:, environment:, key:, value:)` | Create or update secret |
| `delete_secret(project_id:, environment:, key:)` | Delete secret |
| `bulk_import(project_id:, environment:, secrets:)` | Bulk import secrets |
| `load_env(project_id:, environment:)` | Load secrets into ENV |
| `generate_env_file(project_id:, environment:)` | Generate .env file content |
| `list_permissions(project_id:, environment:)` | List permissions |
| `set_permission(project_id:, environment:, user_id:, role:)` | Set permission |
| `delete_permission(project_id:, environment:, user_id:)` | Delete permission |
| `get_my_permissions(project_id:)` | Get current user's permissions |
| `get_project_defaults(project_id:)` | Get default permissions |
| `set_project_defaults(project_id:, defaults:)` | Set default permissions |
| `clear_cache` | Clear secrets cache |
### Examples
#### Rails Application
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
client = KeyEnv::Client.new(token: ENV['KEYENV_TOKEN'])
client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: Rails.env
)
end
```
#### Rails with Credentials
```ruby
# config/initializers/keyenv.rb
if Rails.application.credentials.keyenv&.token
client = KeyEnv::Client.new(token: Rails.application.credentials.keyenv.token)
client.load_env(
project_id: Rails.application.credentials.keyenv.project,
environment: Rails.env
)
end
```
#### Sinatra Application
```ruby
require 'sinatra'
require 'keyenv'
# Load secrets at startup
if ENV['KEYENV_TOKEN']
client = KeyEnv::Client.new(token: ENV['KEYENV_TOKEN'])
client.load_env(project_id: ENV['KEYENV_PROJECT'], environment: 'production')
end
get '/' do
{ status: 'ok' }.to_json
end
get '/config' do
content_type :json
{
api_url: ENV['API_URL']
# Don't expose sensitive secrets!
}.to_json
end
```
#### Sidekiq Worker
```ruby
# config/initializers/sidekiq.rb
Sidekiq.configure_server do |config|
if ENV['KEYENV_TOKEN']
client = KeyEnv::Client.new(
token: ENV['KEYENV_TOKEN'],
cache_ttl: 300 # Cache for 5 minutes
)
client.load_env(project_id: ENV['KEYENV_PROJECT'], environment: Rails.env)
end
end
```
#### Rake Task
```ruby
# lib/tasks/secrets.rake
namespace :secrets do
desc 'Sync secrets from KeyEnv to .env file'
task :sync do
require 'keyenv'
token = ENV['KEYENV_TOKEN'] || raise('KEYENV_TOKEN not set')
project = ENV['KEYENV_PROJECT'] || raise('KEYENV_PROJECT not set')
env = ENV['RAILS_ENV'] || 'development'
client = KeyEnv::Client.new(token: token)
content = client.generate_env_file(project_id: project, environment: env)
File.write('.env', content)
puts "Synced secrets to .env"
end
end
```
#### RSpec Test Setup
```ruby
# spec/support/keyenv.rb
RSpec.configure do |config|
config.before(:suite) do
if ENV['KEYENV_TOKEN']
client = KeyEnv::Client.new(token: ENV['KEYENV_TOKEN'])
client.load_env(project_id: ENV['KEYENV_PROJECT'], environment: 'test')
end
end
end
```
#### AWS Lambda with Ruby
```ruby
require 'keyenv'
# Initialize client outside handler for reuse across invocations
$keyenv_client = KeyEnv::Client.new(
token: ENV['KEYENV_TOKEN'],
cache_ttl: 300 # Cache for 5 minutes in warm lambdas
)
def handler(event:, context:)
# Load secrets (cached after first invocation)
$keyenv_client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: 'production'
)
# Your handler logic here
{
statusCode: 200,
body: JSON.generate({ message: 'Success' })
}
end
```
## .NET SDK
Official .NET SDK for KeyEnv.
Source: https://keyenv.dev/docs/sdks/dotnet/
Official .NET SDK for KeyEnv with .NET 6.0+ support and async/await patterns.
> **Warning**
>
> **Beta Release**: This SDK is currently in development. APIs may change before the stable 1.0 release.
### Installation
#### NuGet Package Manager
```bash
dotnet add package KeyEnv
```
#### Package Manager Console
```powershell
Install-Package KeyEnv
```
#### PackageReference
Add to your `.csproj`:
```xml
```
### Quick Start
```csharp
using KeyEnv;
var client = KeyEnvClient.Create(Environment.GetEnvironmentVariable("KEYENV_TOKEN")!);
// Load secrets into environment variables
int count = await client.LoadEnvAsync("your-project-id", "production");
Console.WriteLine($"Loaded {count} secrets");
// Access secrets
Console.WriteLine(Environment.GetEnvironmentVariable("DATABASE_URL"));
```
### Initialize the Client
#### Simple Initialization
```csharp
using KeyEnv;
var client = KeyEnvClient.Create(Environment.GetEnvironmentVariable("KEYENV_TOKEN")!);
```
#### With Options
For more control, use `KeyEnvOptions`:
```csharp
using KeyEnv;
var client = KeyEnvClient.Create(new KeyEnvOptions
{
Token = Environment.GetEnvironmentVariable("KEYENV_TOKEN")!,
Timeout = TimeSpan.FromSeconds(60),
CacheTtl = TimeSpan.FromMinutes(5)
});
```
### Loading Secrets
#### Load into Environment Variables
The simplest way to use secrets in your application:
```csharp
int count = await client.LoadEnvAsync("project-id", "production");
Console.WriteLine($"Loaded {count} secrets");
// Access via Environment.GetEnvironmentVariable
var dbUrl = Environment.GetEnvironmentVariable("DATABASE_URL");
var apiKey = Environment.GetEnvironmentVariable("API_KEY");
```
#### Get Secrets as Dictionary
Get secrets as a key-value dictionary:
```csharp
var secrets = await client.GetSecretsAsDictionaryAsync("project-id", "production");
Console.WriteLine(secrets["DATABASE_URL"]);
Console.WriteLine(secrets["API_KEY"]);
```
#### Export as List
Get secrets with metadata:
```csharp
var secrets = await client.GetSecretsAsync("project-id", "production");
foreach (var secret in secrets)
{
Console.WriteLine($"{secret.Key}={secret.Value}");
}
```
### Managing Secrets
#### Get a Single Secret
```csharp
var secret = await client.GetSecretAsync("project-id", "production", "DATABASE_URL");
Console.WriteLine(secret.Value);
Console.WriteLine(secret.Description);
```
#### Set a Secret
Creates or updates a secret:
```csharp
await client.SetSecretAsync("project-id", "production", "API_KEY", "sk_live_...");
// With description
await client.SetSecretAsync(
"project-id",
"production",
"API_KEY",
"sk_live_...",
description: "Production API key"
);
```
#### Delete a Secret
```csharp
await client.DeleteSecretAsync("project-id", "production", "OLD_KEY");
```
### Bulk Operations
#### Bulk Import
Import multiple secrets at once:
```csharp
using KeyEnv.Types;
var secrets = new List
{
new SecretInput { Key = "DATABASE_URL", Value = "postgres://localhost/mydb" },
new SecretInput { Key = "REDIS_URL", Value = "redis://localhost:6379" },
new SecretInput { Key = "API_KEY", Value = "sk_test_...", Description = "Test API key" }
};
var result = await client.BulkImportAsync(
"project-id",
"development",
secrets,
new BulkImportOptions { Overwrite = true }
);
Console.WriteLine($"Created: {result.Created}, Updated: {result.Updated}");
```
#### Generate .env File
```csharp
var envContent = await client.GenerateEnvFileAsync("project-id", "production");
await File.WriteAllTextAsync(".env", envContent);
```
### Projects & Environments
#### List Projects
```csharp
var projects = await client.ListProjectsAsync();
foreach (var project in projects)
{
Console.WriteLine($"{project.Name} ({project.Id})");
}
```
#### Get Project Details
```csharp
var project = await client.GetProjectAsync("project-id");
Console.WriteLine($"Project: {project.Name}");
foreach (var env in project.Environments)
{
Console.WriteLine($" - {env.Name}");
}
```
#### List Environments
```csharp
var environments = await client.ListEnvironmentsAsync("project-id");
foreach (var env in environments)
{
Console.WriteLine(env.Name);
}
```
### Environment Permissions
#### List Permissions
```csharp
var permissions = await client.ListPermissionsAsync("project-id", "production");
foreach (var perm in permissions)
{
Console.WriteLine($"{perm.UserEmail}: {perm.Role}");
}
```
#### Set Permission
```csharp
await client.SetPermissionAsync("project-id", "production", "user-id", "write");
```
#### Get My Permissions
```csharp
var response = await client.GetMyPermissionsAsync("project-id");
foreach (var perm in response.Permissions)
{
Console.WriteLine($"{perm.EnvironmentName}: {perm.Role} (CanWrite: {perm.CanWrite})");
}
Console.WriteLine($"Is Team Admin: {response.IsTeamAdmin}");
```
### Caching
Enable caching for better performance in high-throughput applications:
```csharp
var client = KeyEnvClient.Create(new KeyEnvOptions
{
Token = Environment.GetEnvironmentVariable("KEYENV_TOKEN")!,
CacheTtl = TimeSpan.FromMinutes(5)
});
// First call fetches from API
await client.GetSecretsAsync("project-id", "production");
// Subsequent calls within TTL use cache
await client.GetSecretsAsync("project-id", "production");
// Clear cache when needed
client.ClearCache("project-id", "production");
client.ClearAllCache();
```
### Error Handling
```csharp
using KeyEnv;
try
{
var secret = await client.GetSecretAsync("project-id", "production", "MISSING_KEY");
}
catch (KeyEnvException ex)
{
Console.WriteLine($"Error {ex.StatusCode}: {ex.Message}");
if (ex.IsNotFound)
{
Console.WriteLine("Secret not found");
}
else if (ex.IsUnauthorized)
{
Console.WriteLine("Invalid or expired token");
}
else if (ex.IsForbidden)
{
Console.WriteLine("Access denied");
}
}
```
### Cancellation Support
All async methods support cancellation tokens:
```csharp
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
try
{
var secrets = await client.GetSecretsAsync("project-id", "production", cts.Token);
}
catch (OperationCanceledException)
{
Console.WriteLine("Operation was cancelled");
}
```
### IDisposable Pattern
The client implements `IDisposable` for proper resource cleanup:
```csharp
using (var client = KeyEnvClient.Create(token))
{
await client.LoadEnvAsync("project-id", "production");
// Client is disposed when leaving the using block
}
// Or with using declaration (C# 8+)
using var client = KeyEnvClient.Create(token);
await client.LoadEnvAsync("project-id", "production");
```
### API Reference
#### Constructor Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `Token` | `string` | Yes | - | Service token |
| `Timeout` | `TimeSpan?` | No | `30s` | Request timeout |
| `CacheTtl` | `TimeSpan?` | No | `0` | Cache TTL (0 disables) |
| `BaseUrl` | `string?` | No | `https://api.keyenv.dev` | API base URL |
#### Methods
| Method | Description |
|--------|-------------|
| `GetCurrentUserAsync()` | Get current user/token info |
| `ValidateTokenAsync()` | Validate token and get user info |
| `ListProjectsAsync()` | List all accessible projects |
| `GetProjectAsync(projectId)` | Get project with environments |
| `CreateProjectAsync(teamId, name)` | Create a new project |
| `DeleteProjectAsync(projectId)` | Delete a project |
| `ListEnvironmentsAsync(projectId)` | List environments in a project |
| `CreateEnvironmentAsync(projectId, name)` | Create a new environment |
| `DeleteEnvironmentAsync(projectId, env)` | Delete an environment |
| `ListSecretsAsync(projectId, env)` | List secret keys (no values) |
| `GetSecretsAsync(projectId, env)` | Export secrets with values |
| `GetSecretsAsDictionaryAsync(projectId, env)` | Export as dictionary |
| `GetSecretAsync(projectId, env, key)` | Get single secret |
| `SetSecretAsync(projectId, env, key, value)` | Create or update secret |
| `DeleteSecretAsync(projectId, env, key)` | Delete secret |
| `BulkImportAsync(projectId, env, secrets)` | Bulk import secrets |
| `LoadEnvAsync(projectId, env)` | Load secrets into environment |
| `GenerateEnvFileAsync(projectId, env)` | Generate .env file content |
| `GetSecretHistoryAsync(projectId, env, key)` | Get secret version history |
| `ListPermissionsAsync(projectId, env)` | List permissions |
| `SetPermissionAsync(projectId, env, userId, role)` | Set permission |
| `DeletePermissionAsync(projectId, env, userId)` | Delete permission |
| `GetMyPermissionsAsync(projectId)` | Get current user's permissions |
| `GetProjectDefaultsAsync(projectId)` | Get default permissions |
| `SetProjectDefaultsAsync(projectId, defaults)` | Set default permissions |
| `ClearCache(projectId, environment)` | Clear specific cache |
| `ClearAllCache()` | Clear all cached data |
### Examples
#### ASP.NET Core Web API
```csharp
// Program.cs
using KeyEnv;
var builder = WebApplication.CreateBuilder(args);
// Load secrets at startup
var keyEnvToken = Environment.GetEnvironmentVariable("KEYENV_TOKEN");
if (!string.IsNullOrEmpty(keyEnvToken))
{
using var client = KeyEnvClient.Create(keyEnvToken);
await client.LoadEnvAsync(
Environment.GetEnvironmentVariable("KEYENV_PROJECT")!,
builder.Environment.EnvironmentName.ToLower()
);
}
// Now secrets are available via Environment.GetEnvironmentVariable
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();
```
#### ASP.NET Core with Dependency Injection
```csharp
// Program.cs
using KeyEnv;
var builder = WebApplication.CreateBuilder(args);
// Register KeyEnvClient as a singleton
builder.Services.AddSingleton(sp =>
{
return KeyEnvClient.Create(new KeyEnvOptions
{
Token = Environment.GetEnvironmentVariable("KEYENV_TOKEN")!,
CacheTtl = TimeSpan.FromMinutes(5)
});
});
var app = builder.Build();
app.Run();
// In a controller
[ApiController]
[Route("api/[controller]")]
public class SecretsController : ControllerBase
{
private readonly KeyEnvClient _keyEnv;
public SecretsController(KeyEnvClient keyEnv)
{
_keyEnv = keyEnv;
}
[HttpGet]
public async Task Get()
{
var secrets = await _keyEnv.GetSecretsAsDictionaryAsync("project-id", "production");
return Ok(new { count = secrets.Count });
}
}
```
#### Console Application
```csharp
using KeyEnv;
class Program
{
static async Task Main(string[] args)
{
var token = Environment.GetEnvironmentVariable("KEYENV_TOKEN")
?? throw new InvalidOperationException("KEYENV_TOKEN not set");
using var client = KeyEnvClient.Create(token);
// Load all secrets into environment
var count = await client.LoadEnvAsync("my-project", "production");
Console.WriteLine($"Loaded {count} secrets");
// Use the secrets
var dbUrl = Environment.GetEnvironmentVariable("DATABASE_URL");
Console.WriteLine($"Database: {dbUrl}");
}
}
```
#### Azure Functions
```csharp
using KeyEnv;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
var host = new HostBuilder()
.ConfigureFunctionsWebApplication()
.ConfigureServices(services =>
{
services.AddSingleton(sp =>
{
return KeyEnvClient.Create(new KeyEnvOptions
{
Token = Environment.GetEnvironmentVariable("KEYENV_TOKEN")!,
CacheTtl = TimeSpan.FromMinutes(5)
});
});
})
.Build();
// Load secrets at startup
using (var scope = host.Services.CreateScope())
{
var client = scope.ServiceProvider.GetRequiredService();
await client.LoadEnvAsync(
Environment.GetEnvironmentVariable("KEYENV_PROJECT")!,
"production"
);
}
host.Run();
```
#### AWS Lambda with .NET
```csharp
using Amazon.Lambda.Core;
using KeyEnv;
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace MyLambda;
public class Function
{
private static readonly KeyEnvClient _client;
private static bool _secretsLoaded = false;
static Function()
{
_client = KeyEnvClient.Create(new KeyEnvOptions
{
Token = Environment.GetEnvironmentVariable("KEYENV_TOKEN")!,
CacheTtl = TimeSpan.FromMinutes(5)
});
}
public async Task FunctionHandler(object input, ILambdaContext context)
{
// Load secrets once per cold start
if (!_secretsLoaded)
{
await _client.LoadEnvAsync(
Environment.GetEnvironmentVariable("KEYENV_PROJECT")!,
"production"
);
_secretsLoaded = true;
}
// Your handler logic here
var apiKey = Environment.GetEnvironmentVariable("API_KEY");
return $"Success with API key: {apiKey?.Substring(0, 10)}...";
}
}
```
#### Background Service
```csharp
using KeyEnv;
public class SecretsRefreshService : BackgroundService
{
private readonly KeyEnvClient _client;
private readonly ILogger _logger;
public SecretsRefreshService(KeyEnvClient client, ILogger logger)
{
_client = client;
_logger = logger;
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
try
{
var count = await _client.LoadEnvAsync("project-id", "production", stoppingToken);
_logger.LogInformation("Refreshed {Count} secrets", count);
}
catch (Exception ex)
{
_logger.LogError(ex, "Failed to refresh secrets");
}
await Task.Delay(TimeSpan.FromMinutes(5), stoppingToken);
}
}
}
```
## Bun
Using KeyEnv with Bun applications.
Source: https://keyenv.dev/docs/sdks/bun/
Load KeyEnv secrets in your Bun applications using the CLI or the Node.js SDK.
### Using the CLI (Recommended)
The simplest way to use KeyEnv with Bun is via the CLI's `run` command.
#### Install the CLI
```bash
curl -fsSL https://keyenv.dev/install.sh | bash
```
#### Configure package.json
```json
{
"scripts": {
"dev": "keyenv run -p YOUR_PROJECT_ID -e development -- bun run src/index.ts",
"start": "keyenv run -p YOUR_PROJECT_ID -e production -- bun run src/index.ts"
}
}
```
#### Run with Secrets
```bash
# Set your token
export KEYENV_TOKEN=your-service-token
# Run with secrets injected
bun run dev
```
### Using the Node.js SDK
Bun is Node.js-compatible, so you can use the official KeyEnv Node.js SDK.
#### Install
```bash
bun add @keyenv/node
```
#### Basic Usage
```typescript
import { KeyEnv } from '@keyenv/node';
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
// Load secrets into process.env
await client.loadEnv('your-project-id', 'production');
console.log(process.env.DATABASE_URL);
```
#### Full Example
```typescript
// src/index.ts
import { KeyEnv } from '@keyenv/node';
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
// Load secrets before starting server
await client.loadEnv(process.env.KEYENV_PROJECT!, 'production');
const server = Bun.serve({
port: process.env.PORT || 3000,
fetch(req) {
return new Response('OK');
},
});
console.log(`Server running at http://localhost:${server.port}`);
```
### Using Bun's Built-in fetch
You can also call the KeyEnv API directly:
```typescript
const KEYENV_TOKEN = process.env.KEYENV_TOKEN;
const PROJECT_ID = 'your-project-id';
const ENVIRONMENT = 'production';
async function loadSecrets() {
const response = await fetch(
`https://api.keyenv.dev/api/v1/projects/${PROJECT_ID}/environments/${ENVIRONMENT}/secrets/export`,
{
headers: {
'Authorization': `Bearer ${KEYENV_TOKEN}`,
},
}
);
if (!response.ok) {
throw new Error(`Failed to fetch secrets: ${response.status}`);
}
const { data: secrets } = await response.json();
for (const secret of secrets) {
process.env[secret.key] = secret.value;
}
console.log(`Loaded ${secrets.length} secrets`);
}
await loadSecrets();
```
### Elysia Framework
For Elysia applications:
```typescript
import { Elysia } from 'elysia';
import { KeyEnv } from '@keyenv/node';
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
// Load secrets before creating app
await client.loadEnv(process.env.KEYENV_PROJECT!, 'production');
const app = new Elysia()
.get('/', () => 'Hello World')
.get('/config', () => ({
apiUrl: process.env.API_URL,
}))
.listen(3000);
console.log(`Elysia running at http://${app.server?.hostname}:${app.server?.port}`);
```
### Hono Framework
For Hono applications running on Bun:
```typescript
import { Hono } from 'hono';
import { KeyEnv } from '@keyenv/node';
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
await client.loadEnv(process.env.KEYENV_PROJECT!, 'production');
const app = new Hono();
app.get('/', (c) => c.text('Hello World'));
export default {
port: process.env.PORT || 3000,
fetch: app.fetch,
};
```
### Scripts and One-off Commands
For scripts that need secrets:
```typescript
// scripts/migrate.ts
import { KeyEnv } from '@keyenv/node';
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
// Load production secrets for migration
await client.loadEnv(process.env.KEYENV_PROJECT!, 'production');
// Now run your migration
const databaseUrl = process.env.DATABASE_URL;
console.log('Running migrations...');
// ... migration code
```
Run with:
```bash
KEYENV_TOKEN=xxx KEYENV_PROJECT=xxx bun run scripts/migrate.ts
```
Or using the CLI:
```bash
keyenv run -p PROJECT -e production -- bun run scripts/migrate.ts
```
### Testing
Load test secrets in your test setup:
```typescript
// test/setup.ts
import { KeyEnv } from '@keyenv/node';
import { beforeAll } from 'bun:test';
beforeAll(async () => {
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
await client.loadEnv(process.env.KEYENV_PROJECT!, 'test');
});
```
Configure in `bunfig.toml`:
```toml
[test]
preload = ["./test/setup.ts"]
```
### Best Practices
1. **Load secrets once at startup** - Don't fetch on every request:
```typescript
// Good - load once
await client.loadEnv(projectId, 'production');
const server = Bun.serve({ ... });
// Bad - fetching on every request
app.get('/', async () => {
await client.loadEnv(projectId, 'production'); // Don't do this!
});
```
2. **Use environment-specific configs**:
```typescript
const env = process.env.NODE_ENV || 'development';
await client.loadEnv(projectId, env);
```
3. **Handle errors at startup**:
```typescript
try {
await client.loadEnv(projectId, 'production');
} catch (error) {
console.error('Failed to load secrets:', error);
process.exit(1);
}
```
4. **Use caching in serverless** - Enable cache TTL for warm function reuse:
```typescript
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
cacheTtl: 300, // 5 minutes
});
```
## Deno
Using KeyEnv with Deno applications.
Source: https://keyenv.dev/docs/sdks/deno/
Load KeyEnv secrets in your Deno applications using the CLI or direct API calls.
### Using the CLI (Recommended)
The simplest way to use KeyEnv with Deno is via the CLI's `run` command.
#### Install the CLI
```bash
curl -fsSL https://keyenv.dev/install.sh | bash
```
#### Configure deno.json
```json
{
"tasks": {
"dev": "keyenv run -p YOUR_PROJECT_ID -e development -- deno run -A src/main.ts",
"start": "keyenv run -p YOUR_PROJECT_ID -e production -- deno run -A src/main.ts"
}
}
```
#### Run with Secrets
```bash
# Set your token
export KEYENV_TOKEN=your-service-token
# Run with secrets injected
deno task dev
```
### Direct API Usage
Deno has built-in `fetch`, so you can call the KeyEnv API directly without any dependencies.
#### Fetch and Load Secrets
```typescript
const KEYENV_TOKEN = Deno.env.get("KEYENV_TOKEN");
const PROJECT_ID = "your-project-id";
const ENVIRONMENT = "production";
interface Secret {
key: string;
value: string;
}
interface ExportResponse {
data: Secret[];
}
async function loadSecrets(): Promise {
const response = await fetch(
`https://api.keyenv.dev/api/v1/projects/${PROJECT_ID}/environments/${ENVIRONMENT}/secrets/export`,
{
headers: {
"Authorization": `Bearer ${KEYENV_TOKEN}`,
"Content-Type": "application/json",
},
}
);
if (!response.ok) {
throw new Error(`Failed to fetch secrets: ${response.status}`);
}
const data: ExportResponse = await response.json();
for (const secret of data.secrets) {
Deno.env.set(secret.key, secret.value);
}
console.log(`Loaded ${data.secrets.length} secrets`);
}
// Load at startup
await loadSecrets();
// Use secrets
console.log(Deno.env.get("DATABASE_URL"));
```
#### Create a Reusable Module
```typescript
// keyenv.ts
const API_BASE = "https://api.keyenv.dev/api/v1";
export interface KeyEnvConfig {
token: string;
projectId: string;
environment: string;
}
export interface Secret {
key: string;
value: string;
description?: string;
}
export class KeyEnv {
private token: string;
private projectId: string;
private environment: string;
constructor(config: KeyEnvConfig) {
this.token = config.token;
this.projectId = config.projectId;
this.environment = config.environment;
}
private async fetch(path: string, options?: RequestInit): Promise {
const response = await fetch(`${API_BASE}${path}`, {
...options,
headers: {
"Authorization": `Bearer ${this.token}`,
"Content-Type": "application/json",
...options?.headers,
},
});
if (!response.ok) {
const error = await response.json().catch(() => ({}));
throw new Error(error.message || `HTTP ${response.status}`);
}
return response.json();
}
async exportSecrets(): Promise {
const data = await this.fetch<{ data: Secret[] }>(
`/projects/${this.projectId}/environments/${this.environment}/secrets/export`
);
return data.data;
}
async loadEnv(): Promise {
const secrets = await this.exportSecrets();
for (const secret of secrets) {
Deno.env.set(secret.key, secret.value);
}
return secrets.length;
}
async getSecret(key: string): Promise {
return this.fetch(
`/projects/${this.projectId}/environments/${this.environment}/secrets/${key}`
);
}
async setSecret(key: string, value: string, description?: string): Promise {
await this.fetch(
`/projects/${this.projectId}/environments/${this.environment}/secrets/${key}`,
{
method: "PUT",
body: JSON.stringify({ value, description }),
}
);
}
}
```
#### Using the Module
```typescript
// main.ts
import { KeyEnv } from "./keyenv.ts";
const keyenv = new KeyEnv({
token: Deno.env.get("KEYENV_TOKEN")!,
projectId: "your-project-id",
environment: "production",
});
// Load all secrets into environment
await keyenv.loadEnv();
// Or get specific secrets
const dbUrl = await keyenv.getSecret("DATABASE_URL");
console.log(dbUrl.value);
```
### Deno Deploy
For Deno Deploy, use environment variables or the direct API approach.
#### Using Environment Variables
Set `KEYENV_TOKEN` in your Deno Deploy project settings, then fetch secrets at startup:
```typescript
// main.ts
const TOKEN = Deno.env.get("KEYENV_TOKEN");
const PROJECT = Deno.env.get("KEYENV_PROJECT");
// Cache secrets in module scope
let secrets: Map | null = null;
async function getSecrets(): Promise> {
if (secrets) return secrets;
const response = await fetch(
`https://api.keyenv.dev/api/v1/projects/${PROJECT}/environments/production/secrets/export`,
{ headers: { "Authorization": `Bearer ${TOKEN}` } }
);
const data = await response.json();
secrets = new Map(data.secrets.map((s: any) => [s.key, s.value]));
return secrets;
}
Deno.serve(async (_req) => {
const env = await getSecrets();
// Use env.get("DATABASE_URL"), etc.
return new Response("OK");
});
```
### Fresh Framework
For Fresh applications, load secrets in a plugin or middleware:
```typescript
// plugins/keyenv.ts
import { Plugin } from "$fresh/server.ts";
const TOKEN = Deno.env.get("KEYENV_TOKEN");
const PROJECT = Deno.env.get("KEYENV_PROJECT");
export default {
name: "keyenv",
async configureServer() {
const response = await fetch(
`https://api.keyenv.dev/api/v1/projects/${PROJECT}/environments/production/secrets/export`,
{ headers: { "Authorization": `Bearer ${TOKEN}` } }
);
const data = await response.json();
for (const secret of data.secrets) {
Deno.env.set(secret.key, secret.value);
}
console.log(`Loaded ${data.secrets.length} secrets from KeyEnv`);
},
} satisfies Plugin;
```
### Best Practices
1. **Use the CLI for local development** - It handles token management and environment switching.
2. **Cache secrets in production** - Avoid fetching on every request:
```typescript
let cachedSecrets: Map | null = null;
let cacheExpiry = 0;
async function getSecrets() {
if (cachedSecrets && Date.now() < cacheExpiry) {
return cachedSecrets;
}
// Fetch and cache for 5 minutes
cachedSecrets = await fetchSecrets();
cacheExpiry = Date.now() + 5 * 60 * 1000;
return cachedSecrets;
}
```
3. **Handle errors gracefully**:
```typescript
try {
await loadSecrets();
} catch (error) {
console.error("Failed to load secrets:", error);
Deno.exit(1);
}
```
4. **Don't commit tokens** - Use environment variables or a `.env` file (gitignored).
## Next.js Integration
Use KeyEnv secrets securely in Next.js applications.
Source: https://keyenv.dev/docs/sdks/nextjs/
Integrate KeyEnv secrets into your Next.js application with proper security practices for server and client components.
### Features
- Load secrets at build time or runtime
- Server Components and Server Actions support
- API Routes and Route Handlers support
- Middleware integration
- Environment-aware configuration
- Works with App Router and Pages Router
- Vercel deployment ready
### Installation
```bash
npm install @keyenv/node
```
Or with other package managers:
```bash
yarn add @keyenv/node
pnpm add @keyenv/node
```
### Quick Start
The recommended approach is to load secrets once at application startup.
#### App Router (Recommended)
Create a secrets loader in your app:
```typescript
// lib/secrets.ts
import { KeyEnv } from '@keyenv/node';
let secretsLoaded = false;
export async function loadSecrets() {
if (secretsLoaded) return;
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
await client.loadEnv(
process.env.KEYENV_PROJECT_ID!,
process.env.NODE_ENV === 'production' ? 'production' : 'development'
);
secretsLoaded = true;
}
```
Then call it in your layout or specific routes:
```typescript
// app/layout.tsx
import { loadSecrets } from '@/lib/secrets';
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
await loadSecrets();
return (
{children}
);
}
```
---
### next.config.js Integration
For build-time secret injection, use a custom webpack configuration:
```javascript
// next.config.js
const { KeyEnv } = require('@keyenv/node');
/** @type {import('next').NextConfig} */
const nextConfig = {
// Other config options...
};
// Load secrets at build time
async function loadBuildSecrets() {
if (!process.env.KEYENV_TOKEN) {
console.warn('KEYENV_TOKEN not set, skipping secret loading');
return {};
}
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN,
});
const env = process.env.VERCEL_ENV || process.env.NODE_ENV;
const environment = env === 'production' ? 'production' : 'development';
return await client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID,
environment
);
}
module.exports = async () => {
const secrets = await loadBuildSecrets();
return {
...nextConfig,
env: {
...secrets,
},
};
};
```
> **Warning**
>
> Build-time secrets are embedded in the bundle. Only use this for non-sensitive configuration. For sensitive secrets, load them at runtime in Server Components.
---
### Server Components vs Client Components
Next.js has different execution contexts. Understanding where secrets are safe is critical.
| Context | Secrets Safe? | Access Method |
|---------|---------------|---------------|
| Server Components | Yes | `process.env.SECRET` |
| Server Actions | Yes | `process.env.SECRET` |
| API Routes / Route Handlers | Yes | `process.env.SECRET` |
| Middleware | Yes | `process.env.SECRET` |
| Client Components | No | Never expose secrets |
#### Server Components (Safe)
Server Components run only on the server. Secrets are never sent to the browser:
```typescript
// app/dashboard/page.tsx
import { KeyEnv } from '@keyenv/node';
export default async function DashboardPage() {
// Safe: This code only runs on the server
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
const secrets = await client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
'production'
);
// Use the secret to fetch data
const data = await fetch('https://api.example.com/data', {
headers: {
Authorization: `Bearer ${secrets.API_KEY}`,
},
});
return
{/* Render data, not secrets */}
;
}
```
#### Client Components (Never Use Secrets)
Client Components run in the browser. Never access secrets here:
```typescript
// components/UserProfile.tsx
'use client';
// WRONG: Never do this in a client component
// const apiKey = process.env.API_KEY; // This would be undefined or leaked
// CORRECT: Fetch data through an API route instead
export function UserProfile() {
const [data, setData] = useState(null);
useEffect(() => {
fetch('/api/user-data')
.then(res => res.json())
.then(setData);
}, []);
return
{/* Render data */}
;
}
```
#### Public Environment Variables
For non-sensitive values needed in the browser, use the `NEXT_PUBLIC_` prefix:
```bash
# In KeyEnv, create these secrets:
NEXT_PUBLIC_APP_URL=https://myapp.com
NEXT_PUBLIC_ANALYTICS_ID=UA-123456789
```
```typescript
// components/Analytics.tsx
'use client';
export function Analytics() {
// Safe: These are intentionally public
const analyticsId = process.env.NEXT_PUBLIC_ANALYTICS_ID;
return ;
}
```
> **Warning**
>
> Only use `NEXT_PUBLIC_` for values that are safe to expose to users. These are embedded in the client JavaScript bundle.
---
### API Routes / Route Handlers
#### App Router (Route Handlers)
```typescript
// app/api/data/route.ts
import { KeyEnv } from '@keyenv/node';
import { NextResponse } from 'next/server';
// Cache the client instance
let client: KeyEnv | null = null;
function getClient() {
if (!client) {
client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
}
return client;
}
export async function GET() {
const keyenv = getClient();
const secrets = await keyenv.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
'production'
);
// Use secrets to call external APIs
const response = await fetch('https://api.stripe.com/v1/charges', {
headers: {
Authorization: `Bearer ${secrets.STRIPE_SECRET_KEY}`,
},
});
const data = await response.json();
return NextResponse.json(data);
}
```
#### Pages Router (API Routes)
```typescript
// pages/api/data.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { KeyEnv } from '@keyenv/node';
let secretsLoaded = false;
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
// Load secrets once
if (!secretsLoaded) {
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
await client.loadEnv(process.env.KEYENV_PROJECT_ID!, 'production');
secretsLoaded = true;
}
// Now use process.env
const apiKey = process.env.API_KEY;
res.status(200).json({ status: 'ok' });
}
```
---
### Server Actions
Server Actions are secure server-side functions. Secrets are safe to use:
```typescript
// app/actions.ts
'use server';
import { KeyEnv } from '@keyenv/node';
export async function submitPayment(formData: FormData) {
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
const secrets = await client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
'production'
);
// Safe: Server Action runs only on the server
const response = await fetch('https://api.stripe.com/v1/charges', {
method: 'POST',
headers: {
Authorization: `Bearer ${secrets.STRIPE_SECRET_KEY}`,
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
amount: formData.get('amount') as string,
currency: 'usd',
}),
});
return response.json();
}
```
---
### Middleware
Use KeyEnv in Next.js middleware for authentication or request processing:
```typescript
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { KeyEnv } from '@keyenv/node';
// Cache secrets at module level
let cachedSecrets: Record | null = null;
async function getSecrets() {
if (cachedSecrets) return cachedSecrets;
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
cachedSecrets = await client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
'production'
);
return cachedSecrets;
}
export async function middleware(request: NextRequest) {
const secrets = await getSecrets();
// Example: Validate API key in header
const apiKey = request.headers.get('x-api-key');
if (apiKey !== secrets.VALID_API_KEY) {
return NextResponse.json(
{ error: 'Unauthorized' },
{ status: 401 }
);
}
return NextResponse.next();
}
export const config = {
matcher: '/api/:path*',
};
```
> **Note**
>
> Middleware runs on the Edge Runtime. The KeyEnv SDK is compatible with Edge Runtime environments.
---
### Environment-Aware Configuration
Automatically select the right environment based on deployment context:
```typescript
// lib/keyenv.ts
import { KeyEnv } from '@keyenv/node';
export function getEnvironment(): string {
// Vercel provides VERCEL_ENV
if (process.env.VERCEL_ENV) {
switch (process.env.VERCEL_ENV) {
case 'production':
return 'production';
case 'preview':
return 'staging';
default:
return 'development';
}
}
// Fallback to NODE_ENV
return process.env.NODE_ENV === 'production' ? 'production' : 'development';
}
let client: KeyEnv | null = null;
let loadedEnvironment: string | null = null;
export async function getSecrets(): Promise> {
const environment = getEnvironment();
// Reload if environment changed (shouldn't happen, but safety first)
if (client && loadedEnvironment === environment) {
return client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
environment
);
}
client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
loadedEnvironment = environment;
return client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
environment
);
}
```
Usage:
```typescript
// app/api/config/route.ts
import { getSecrets, getEnvironment } from '@/lib/keyenv';
export async function GET() {
const secrets = await getSecrets();
return Response.json({
environment: getEnvironment(),
// Only return non-sensitive config
apiUrl: secrets.API_URL,
});
}
```
---
### Vercel Deployment
KeyEnv works seamlessly with Vercel. See our dedicated [Vercel Integration Guide](/docs/guides/vercel) for complete setup instructions.
#### Quick Setup
1. **Create a Service Token** in KeyEnv dashboard
2. **Add to Vercel** environment variables:
- `KEYENV_TOKEN`: Your service token
- `KEYENV_PROJECT_ID`: Your KeyEnv project ID
3. **Environment Mapping**:
| Vercel Environment | KeyEnv Environment |
|--------------------|-------------------|
| Production | `production` |
| Preview | `staging` |
| Development | `development` |
#### Recommended: Native Sync
For production apps, use KeyEnv's native Vercel sync:
1. Go to **Settings** > **Integrations** in KeyEnv
2. Connect your Vercel account
3. Map environments
4. Secrets sync automatically
This ensures secrets are available at both build time and runtime without any code changes.
---
### Caching Best Practices
#### Singleton Pattern
Cache the KeyEnv client to avoid re-initialization:
```typescript
// lib/keyenv.ts
import { KeyEnv } from '@keyenv/node';
let client: KeyEnv | null = null;
let secretsCache: Record | null = null;
export async function getSecrets(): Promise> {
if (secretsCache) return secretsCache;
if (!client) {
client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
}
secretsCache = await client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
process.env.NODE_ENV === 'production' ? 'production' : 'development'
);
return secretsCache;
}
// For use in Server Components
export async function getSecret(key: string): Promise {
const secrets = await getSecrets();
return secrets[key];
}
```
#### With React Cache
For App Router, use React's cache function:
```typescript
// lib/keyenv.ts
import { cache } from 'react';
import { KeyEnv } from '@keyenv/node';
export const getSecrets = cache(async () => {
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
return client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
process.env.NODE_ENV === 'production' ? 'production' : 'development'
);
});
```
This deduplicates requests within a single render pass.
---
### Complete Example
#### Project Structure
```
my-nextjs-app/
├── app/
│ ├── api/
│ │ └── data/
│ │ └── route.ts
│ ├── dashboard/
│ │ └── page.tsx
│ ├── actions.ts
│ └── layout.tsx
├── lib/
│ └── keyenv.ts
├── middleware.ts
├── next.config.js
└── package.json
```
#### lib/keyenv.ts
```typescript
import { cache } from 'react';
import { KeyEnv } from '@keyenv/node';
function getEnvironment(): string {
if (process.env.VERCEL_ENV === 'production') return 'production';
if (process.env.VERCEL_ENV === 'preview') return 'staging';
return 'development';
}
export const getSecrets = cache(async () => {
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
return client.exportSecretsAsObject(
process.env.KEYENV_PROJECT_ID!,
getEnvironment()
);
});
export async function getSecret(key: string): Promise {
const secrets = await getSecrets();
return secrets[key];
}
```
#### app/dashboard/page.tsx
```typescript
import { getSecret } from '@/lib/keyenv';
export default async function DashboardPage() {
const apiKey = await getSecret('EXTERNAL_API_KEY');
const data = await fetch('https://api.example.com/data', {
headers: { Authorization: `Bearer ${apiKey}` },
});
return (
Dashboard
{/* Render data */}
);
}
```
#### app/api/data/route.ts
```typescript
import { getSecrets } from '@/lib/keyenv';
import { NextResponse } from 'next/server';
export async function GET() {
const secrets = await getSecrets();
const response = await fetch('https://api.example.com/data', {
headers: {
Authorization: `Bearer ${secrets.API_KEY}`,
},
});
return NextResponse.json(await response.json());
}
```
#### Environment Variables
Set these in your deployment environment (Vercel, etc.):
```bash
KEYENV_TOKEN=env_your_service_token
KEYENV_PROJECT_ID=proj_your_project_id
```
---
### TypeScript Support
The KeyEnv SDK includes full TypeScript support:
```typescript
import { KeyEnv } from '@keyenv/node';
import type { Secret, SecretWithValue } from '@keyenv/node';
```
For type-safe environment variables, create a declaration file:
```typescript
// env.d.ts
declare namespace NodeJS {
interface ProcessEnv {
KEYENV_TOKEN: string;
KEYENV_PROJECT_ID: string;
DATABASE_URL: string;
API_KEY: string;
// Add your other secrets here
}
}
```
---
### Troubleshooting
#### "KEYENV_TOKEN is not defined"
Ensure the environment variable is set in your deployment platform (Vercel, etc.) and is available at runtime.
#### Secrets not available in Client Components
This is by design. Client Components run in the browser where secrets should never be exposed. Use Server Components, API Routes, or Server Actions instead.
#### "Error: Dynamic server usage"
If you see this error, it means you're trying to use secrets in a static context. Either:
1. Make the page dynamic with `export const dynamic = 'force-dynamic'`
2. Load secrets at build time via `next.config.js`
#### Secrets not updating after change
If using caching, you may need to redeploy. For Vercel, enable auto-redeploy in KeyEnv's native sync settings.
#### Edge Runtime compatibility
The KeyEnv SDK works with Edge Runtime. If you encounter issues, ensure you're using the latest version of the SDK.
---
### Security Best Practices
1. **Never expose secrets to the client** - Use Server Components, API Routes, or Server Actions
2. **Use environment-specific tokens** - Create separate tokens for production and staging
3. **Scope tokens narrowly** - Only grant access to required environments
4. **Use `NEXT_PUBLIC_` intentionally** - Only for truly public values
5. **Cache secrets** - Reduce API calls and improve performance
6. **Review token permissions** - Regularly audit service token access
## Django Integration
Use KeyEnv with Django applications for secure secrets management.
Source: https://keyenv.dev/docs/sdks/django/
Integrate KeyEnv with your Django application to securely manage secrets like database credentials, API keys, and the Django secret key.
### Features
- Load secrets before Django initializes
- Environment-aware configuration (development, staging, production)
- Works with django-environ and python-decouple patterns
- Supports DATABASE_URL parsing
- Type-safe with full Python type annotations
### Installation
```bash
pip install keyenv
```
Or with poetry:
```bash
poetry add keyenv
```
For DATABASE_URL parsing, also install dj-database-url:
```bash
pip install dj-database-url
```
### Quick Start
Add KeyEnv to the top of your `settings.py`:
```python
# settings.py
from keyenv import KeyEnv
import os
# Load secrets before anything else
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(
os.environ["KEYENV_PROJECT"],
os.environ.get("DJANGO_ENV", "development")
)
# Now use secrets in your settings
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DEBUG", "false").lower() == "true"
```
### Django Settings Integration
#### Basic Setup
The simplest approach loads all secrets into `os.environ` at startup:
```python
# settings.py
from keyenv import KeyEnv
import os
# Load secrets from KeyEnv
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
env = os.environ.get("DJANGO_ENV", "development")
client.load_env(os.environ["KEYENV_PROJECT"], env)
# Django settings
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DEBUG", "false").lower() == "true"
ALLOWED_HOSTS = os.environ.get("ALLOWED_HOSTS", "localhost").split(",")
# Database
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"HOST": os.environ.get("DB_HOST", "localhost"),
"PORT": os.environ.get("DB_PORT", "5432"),
"NAME": os.environ.get("DB_NAME", "myapp"),
"USER": os.environ.get("DB_USER", "postgres"),
"PASSWORD": os.environ.get("DB_PASSWORD", ""),
}
}
# Email
EMAIL_HOST = os.environ.get("EMAIL_HOST", "smtp.gmail.com")
EMAIL_HOST_USER = os.environ.get("EMAIL_HOST_USER", "")
EMAIL_HOST_PASSWORD = os.environ.get("EMAIL_HOST_PASSWORD", "")
```
#### With DATABASE_URL
Use `dj-database-url` for cleaner database configuration:
```python
# settings.py
from keyenv import KeyEnv
import dj_database_url
import os
# Load secrets
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], os.environ.get("DJANGO_ENV", "development"))
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
# Parse DATABASE_URL automatically
DATABASES = {
"default": dj_database_url.config(
default="postgres://localhost/myapp",
conn_max_age=600,
conn_health_checks=True,
)
}
```
Store your database URL in KeyEnv as:
```
DATABASE_URL=postgres://user:password@host:5432/dbname
```
### Environment-Aware Configuration
#### Automatic Environment Detection
Detect the environment from various sources:
```python
# settings.py
from keyenv import KeyEnv
import os
def get_environment():
"""Determine environment from various sources."""
# Check explicit setting first
if env := os.environ.get("DJANGO_ENV"):
return env
# Check common deployment indicators
if os.environ.get("RAILWAY_ENVIRONMENT"):
return os.environ["RAILWAY_ENVIRONMENT"]
if os.environ.get("RENDER"):
return "production"
if os.environ.get("HEROKU_APP_NAME"):
return "production"
# Default to development
return "development"
ENVIRONMENT = get_environment()
# Load environment-specific secrets
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], ENVIRONMENT)
# Environment-specific settings
DEBUG = ENVIRONMENT == "development"
```
#### Split Settings Pattern
For larger projects, use environment-specific settings files:
```python
# settings/base.py
from keyenv import KeyEnv
import os
ENVIRONMENT = os.environ.get("DJANGO_ENV", "development")
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], ENVIRONMENT)
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
# Common settings...
INSTALLED_APPS = [...]
MIDDLEWARE = [...]
```
```python
# settings/development.py
from .base import *
DEBUG = True
ALLOWED_HOSTS = ["localhost", "127.0.0.1"]
```
```python
# settings/production.py
from .base import *
DEBUG = False
ALLOWED_HOSTS = os.environ.get("ALLOWED_HOSTS", "").split(",")
# Production-specific settings
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
```
### Using with django-environ
If you prefer django-environ's API:
```python
# settings.py
from keyenv import KeyEnv
import environ
import os
# Load KeyEnv secrets first
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], os.environ.get("DJANGO_ENV", "development"))
# Initialize django-environ (reads from os.environ)
env = environ.Env(
DEBUG=(bool, False),
ALLOWED_HOSTS=(list, ["localhost"]),
)
# Use django-environ's typed accessors
SECRET_KEY = env("DJANGO_SECRET_KEY")
DEBUG = env("DEBUG")
ALLOWED_HOSTS = env("ALLOWED_HOSTS")
DATABASES = {
"default": env.db("DATABASE_URL", default="postgres://localhost/myapp")
}
EMAIL_CONFIG = env.email_url("EMAIL_URL", default="smtp://localhost:25")
```
### Using with python-decouple
If you prefer python-decouple's pattern:
```python
# settings.py
from keyenv import KeyEnv
from decouple import config, Csv
import os
# Load KeyEnv secrets first
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], os.environ.get("DJANGO_ENV", "development"))
# python-decouple reads from os.environ (and .env as fallback)
SECRET_KEY = config("DJANGO_SECRET_KEY")
DEBUG = config("DEBUG", default=False, cast=bool)
ALLOWED_HOSTS = config("ALLOWED_HOSTS", default="localhost", cast=Csv())
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"HOST": config("DB_HOST", default="localhost"),
"PORT": config("DB_PORT", default=5432, cast=int),
"NAME": config("DB_NAME", default="myapp"),
"USER": config("DB_USER", default="postgres"),
"PASSWORD": config("DB_PASSWORD", default=""),
}
}
```
### Complete Example
Here's a complete `settings.py` for a production Django application:
```python
# settings.py
from keyenv import KeyEnv
from pathlib import Path
import dj_database_url
import os
# Build paths
BASE_DIR = Path(__file__).resolve().parent.parent
# Determine environment
ENVIRONMENT = os.environ.get("DJANGO_ENV", "development")
# Load secrets from KeyEnv
if token := os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=token)
project_id = os.environ.get("KEYENV_PROJECT")
if project_id:
client.load_env(project_id, ENVIRONMENT)
# Core settings
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DEBUG", "false").lower() == "true"
ALLOWED_HOSTS = os.environ.get("ALLOWED_HOSTS", "localhost").split(",")
# Application definition
INSTALLED_APPS = [
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
# Your apps
"myapp",
]
MIDDLEWARE = [
"django.middleware.security.SecurityMiddleware",
"whitenoise.middleware.WhiteNoiseMiddleware",
"django.contrib.sessions.middleware.SessionMiddleware",
"django.middleware.common.CommonMiddleware",
"django.middleware.csrf.CsrfViewMiddleware",
"django.contrib.auth.middleware.AuthenticationMiddleware",
"django.contrib.messages.middleware.MessageMiddleware",
"django.middleware.clickjacking.XFrameOptionsMiddleware",
]
ROOT_URLCONF = "myproject.urls"
WSGI_APPLICATION = "myproject.wsgi.application"
# Database
DATABASES = {
"default": dj_database_url.config(
default="postgres://localhost/myapp",
conn_max_age=600,
conn_health_checks=True,
)
}
# Cache (optional)
if redis_url := os.environ.get("REDIS_URL"):
CACHES = {
"default": {
"BACKEND": "django.core.cache.backends.redis.RedisCache",
"LOCATION": redis_url,
}
}
# Email
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = os.environ.get("EMAIL_HOST", "smtp.gmail.com")
EMAIL_PORT = int(os.environ.get("EMAIL_PORT", "587"))
EMAIL_USE_TLS = os.environ.get("EMAIL_USE_TLS", "true").lower() == "true"
EMAIL_HOST_USER = os.environ.get("EMAIL_HOST_USER", "")
EMAIL_HOST_PASSWORD = os.environ.get("EMAIL_HOST_PASSWORD", "")
DEFAULT_FROM_EMAIL = os.environ.get("DEFAULT_FROM_EMAIL", "noreply@example.com")
# Security (production)
if ENVIRONMENT == "production":
SECURE_SSL_REDIRECT = True
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
# Static files
STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
STATICFILES_STORAGE = "whitenoise.storage.CompressedManifestStaticFilesStorage"
# Third-party services
STRIPE_SECRET_KEY = os.environ.get("STRIPE_SECRET_KEY", "")
STRIPE_WEBHOOK_SECRET = os.environ.get("STRIPE_WEBHOOK_SECRET", "")
SENTRY_DSN = os.environ.get("SENTRY_DSN", "")
# Initialize Sentry
if SENTRY_DSN:
import sentry_sdk
sentry_sdk.init(
dsn=SENTRY_DSN,
environment=ENVIRONMENT,
traces_sample_rate=0.1,
)
```
### Setting Up Your Deployment
#### Required Environment Variables
Set these in your deployment platform (not in KeyEnv):
| Variable | Description |
|----------|-------------|
| `KEYENV_TOKEN` | Your KeyEnv service token |
| `KEYENV_PROJECT` | Your KeyEnv project ID |
| `DJANGO_ENV` | Environment name (development, staging, production) |
#### Secrets to Store in KeyEnv
Store these secrets in KeyEnv for each environment:
| Secret | Description | Example |
|--------|-------------|---------|
| `DJANGO_SECRET_KEY` | Django secret key | `django-insecure-abc123...` |
| `DATABASE_URL` | Database connection string | `postgres://user:pass@host/db` |
| `REDIS_URL` | Redis connection (optional) | `redis://localhost:6379/0` |
| `EMAIL_HOST_PASSWORD` | SMTP password | `app-specific-password` |
| `STRIPE_SECRET_KEY` | Stripe API key | `sk_live_...` |
| `SENTRY_DSN` | Sentry DSN | `https://...@sentry.io/...` |
| `ALLOWED_HOSTS` | Comma-separated hosts | `example.com,www.example.com` |
#### Generate a Django Secret Key
```bash
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
```
### Local Development
For local development without KeyEnv:
```python
# settings.py - handles missing KEYENV_TOKEN gracefully
if os.environ.get("KEYENV_TOKEN"):
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], "development")
# Falls back to local .env file or defaults
SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "dev-secret-key-not-for-production")
```
Or use the KeyEnv CLI to generate a `.env` file:
```bash
keyenv pull --env development --output .env
```
Then load it with python-dotenv in development:
```python
# settings.py
import os
if os.environ.get("KEYENV_TOKEN"):
from keyenv import KeyEnv
client = KeyEnv(token=os.environ["KEYENV_TOKEN"])
client.load_env(os.environ["KEYENV_PROJECT"], os.environ.get("DJANGO_ENV", "development"))
elif os.path.exists(".env"):
from dotenv import load_dotenv
load_dotenv()
```
### wsgi.py and asgi.py
No changes needed to `wsgi.py` or `asgi.py`. Secrets are loaded when `settings.py` is imported.
### Testing
For tests, you can skip KeyEnv by not setting `KEYENV_TOKEN`:
```python
# conftest.py (pytest)
import os
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
# Test-specific secrets
os.environ["DJANGO_SECRET_KEY"] = "test-secret-key"
os.environ["DATABASE_URL"] = "postgres://localhost/test_db"
```
Or use pytest-env:
```ini
# pytest.ini
[pytest]
env =
DJANGO_SECRET_KEY=test-secret-key
DATABASE_URL=postgres://localhost/test_db
```
### Troubleshooting
#### "KEYENV_TOKEN not set"
In production, ensure `KEYENV_TOKEN` is set in your deployment platform's environment variables (Heroku Config Vars, Railway Variables, etc.).
#### "Project not found"
Verify `KEYENV_PROJECT` matches your project ID in the KeyEnv dashboard.
#### "Environment not found"
Check that the environment name (development, staging, production) exists in your KeyEnv project.
#### Secrets not loading
1. Check that `load_env()` is called before accessing `os.environ`
2. Verify the service token has read access to the environment
3. Check for typos in secret key names
#### Performance
`load_env()` makes a single API call at startup. Secrets are cached in `os.environ` for the lifetime of the process. There's no runtime overhead after initialization.
## Laravel Integration
Use KeyEnv with Laravel applications for secure secrets management.
Source: https://keyenv.dev/docs/sdks/laravel/
Integrate KeyEnv with your Laravel application to securely manage secrets like database credentials, API keys, and encryption keys.
### Features
- Load secrets before Laravel initializes
- Environment-aware configuration (local, staging, production)
- Service Provider with auto-discovery
- Facade for convenient access (`KeyEnv::get('key')`)
- Artisan commands for local development
- Works with Laravel's `.env` file pattern
- Supports Laravel 9.x, 10.x, and 11.x
### Installation
```bash
composer require keyenv/keyenv
```
### Quick Start
The simplest approach loads secrets in your `AppServiceProvider`:
```php
// app/Providers/AppServiceProvider.php
namespace App\Providers;
use Illuminate\Support\ServiceProvider;
use KeyEnv\KeyEnv;
class AppServiceProvider extends ServiceProvider
{
public function register(): void
{
// Load secrets before config is used
if ($token = env('KEYENV_TOKEN')) {
$client = KeyEnv::create($token);
$client->loadEnv(
env('KEYENV_PROJECT'),
env('APP_ENV', 'local')
);
}
}
public function boot(): void
{
//
}
}
```
### Service Provider Setup
For a more robust setup, create a dedicated KeyEnv service provider:
#### Create the Service Provider
```bash
php artisan make:provider KeyEnvServiceProvider
```
```php
// app/Providers/KeyEnvServiceProvider.php
namespace App\Providers;
use Illuminate\Support\ServiceProvider;
use KeyEnv\KeyEnv;
class KeyEnvServiceProvider extends ServiceProvider
{
public function register(): void
{
// Register the KeyEnv client as a singleton
$this->app->singleton(KeyEnv::class, function () {
$token = env('KEYENV_TOKEN');
if (!$token) {
return null;
}
return KeyEnv::create($token);
});
// Load secrets into environment
$this->loadSecrets();
}
protected function loadSecrets(): void
{
$token = env('KEYENV_TOKEN');
$projectId = env('KEYENV_PROJECT');
if (!$token || !$projectId) {
return;
}
$client = KeyEnv::create($token);
$environment = $this->mapLaravelEnv(env('APP_ENV', 'local'));
$client->loadEnv($projectId, $environment);
}
protected function mapLaravelEnv(string $laravelEnv): string
{
// Map Laravel environments to KeyEnv environments
return match ($laravelEnv) {
'local' => 'development',
'testing' => 'development',
'staging' => 'staging',
'production', 'prod' => 'production',
default => $laravelEnv,
};
}
public function boot(): void
{
//
}
}
```
#### Register the Provider
Add to `bootstrap/providers.php` (Laravel 11):
```php
return [
App\Providers\AppServiceProvider::class,
App\Providers\KeyEnvServiceProvider::class, // Add this line
];
```
Or in `config/app.php` (Laravel 9/10):
```php
'providers' => ServiceProvider::defaultProviders()->merge([
App\Providers\KeyEnvServiceProvider::class,
])->toArray(),
```
### Config File Setup
Create a config file for KeyEnv settings:
```php
// config/keyenv.php
return [
/*
|--------------------------------------------------------------------------
| KeyEnv Service Token
|--------------------------------------------------------------------------
|
| Your KeyEnv service token for API authentication.
| Generate one at: https://app.keyenv.dev/settings/tokens
|
*/
'token' => env('KEYENV_TOKEN'),
/*
|--------------------------------------------------------------------------
| KeyEnv Project ID
|--------------------------------------------------------------------------
|
| The ID of your KeyEnv project.
|
*/
'project_id' => env('KEYENV_PROJECT'),
/*
|--------------------------------------------------------------------------
| Environment Mapping
|--------------------------------------------------------------------------
|
| Map Laravel environment names to KeyEnv environment names.
|
*/
'environments' => [
'local' => 'development',
'testing' => 'development',
'staging' => 'staging',
'production' => 'production',
],
/*
|--------------------------------------------------------------------------
| Enabled
|--------------------------------------------------------------------------
|
| Enable or disable KeyEnv secret loading. Useful for disabling
| in local development when using .env files.
|
*/
'enabled' => env('KEYENV_ENABLED', true),
/*
|--------------------------------------------------------------------------
| Request Timeout
|--------------------------------------------------------------------------
|
| Timeout in seconds for API requests.
|
*/
'timeout' => env('KEYENV_TIMEOUT', 30),
];
```
Update the service provider to use the config:
```php
// app/Providers/KeyEnvServiceProvider.php
protected function loadSecrets(): void
{
if (!config('keyenv.enabled')) {
return;
}
$token = config('keyenv.token');
$projectId = config('keyenv.project_id');
if (!$token || !$projectId) {
return;
}
$client = KeyEnv::create($token, config('keyenv.timeout', 30));
$laravelEnv = app()->environment();
$keyenvEnv = config("keyenv.environments.{$laravelEnv}", $laravelEnv);
$client->loadEnv($projectId, $keyenvEnv);
}
```
### Facade Usage
Create a Facade for convenient access to KeyEnv:
```php
// app/Facades/KeyEnv.php
namespace App\Facades;
use Illuminate\Support\Facades\Facade;
/**
* @method static array exportSecrets(string $projectId, string $environment)
* @method static array exportSecretsAsArray(string $projectId, string $environment)
* @method static \KeyEnv\Types\SecretWithValue getSecret(string $projectId, string $environment, string $key)
* @method static int loadEnv(string $projectId, string $environment)
*
* @see \KeyEnv\KeyEnv
*/
class KeyEnv extends Facade
{
protected static function getFacadeAccessor(): string
{
return \KeyEnv\KeyEnv::class;
}
}
```
Register an alias in `config/app.php`:
```php
'aliases' => Facade::defaultAliases()->merge([
'KeyEnv' => App\Facades\KeyEnv::class,
])->toArray(),
```
Now you can use the Facade:
```php
use App\Facades\KeyEnv;
// Get a single secret
$secret = KeyEnv::getSecret(
config('keyenv.project_id'),
'production',
'STRIPE_SECRET_KEY'
);
echo $secret->value;
// Get all secrets as array
$secrets = KeyEnv::exportSecretsAsArray(
config('keyenv.project_id'),
'production'
);
```
### Environment-Aware Configuration
#### Automatic Environment Detection
```php
// app/Providers/KeyEnvServiceProvider.php
protected function mapLaravelEnv(string $laravelEnv): string
{
// Check for explicit KeyEnv environment override
if ($override = env('KEYENV_ENV')) {
return $override;
}
// Check for deployment platform indicators
if (env('VAPOR_SSM_PATH')) {
return 'production'; // AWS Lambda via Vapor
}
if (env('FORGE_SERVER_ID')) {
return 'production'; // Laravel Forge
}
if (env('RENDER')) {
return 'production'; // Render
}
// Map standard Laravel environments
return match ($laravelEnv) {
'local', 'development' => 'development',
'testing' => 'development',
'staging' => 'staging',
'production', 'prod' => 'production',
default => $laravelEnv,
};
}
```
#### Per-Environment .env Files
Laravel supports environment-specific `.env` files. You can use different KeyEnv configurations:
```bash
# .env.local (development)
KEYENV_TOKEN=env_dev_...
KEYENV_PROJECT=your-project-id
KEYENV_ENV=development
# .env.production
KEYENV_TOKEN=env_prod_...
KEYENV_PROJECT=your-project-id
KEYENV_ENV=production
```
### Using with .env Files
KeyEnv complements Laravel's `.env` pattern. Secrets loaded via `loadEnv()` are available through `env()` and `config()`:
#### Bridge Pattern
Load KeyEnv secrets, then use them in your Laravel config:
```php
// config/database.php
return [
'default' => env('DB_CONNECTION', 'pgsql'),
'connections' => [
'pgsql' => [
'driver' => 'pgsql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '5432'),
'database' => env('DB_DATABASE', 'laravel'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
// These values come from KeyEnv via loadEnv()
],
],
];
```
```php
// config/mail.php
return [
'default' => env('MAIL_MAILER', 'smtp'),
'mailers' => [
'smtp' => [
'transport' => 'smtp',
'host' => env('MAIL_HOST', 'smtp.mailgun.org'),
'port' => env('MAIL_PORT', 587),
'encryption' => env('MAIL_ENCRYPTION', 'tls'),
'username' => env('MAIL_USERNAME'),
'password' => env('MAIL_PASSWORD'),
],
],
];
```
#### Generate .env from KeyEnv
Use the KeyEnv CLI to generate a local `.env` file:
```bash
# Pull secrets to .env file
keyenv pull --env development --output .env
# Or use the PHP SDK
php -r "
require 'vendor/autoload.php';
\$client = KeyEnv\KeyEnv::create(getenv('KEYENV_TOKEN'));
echo \$client->generateEnvFile(getenv('KEYENV_PROJECT'), 'development');
" > .env
```
### Artisan Commands
Create custom Artisan commands for KeyEnv operations:
#### keyenv:pull Command
```php
// app/Console/Commands/KeyEnvPull.php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use KeyEnv\KeyEnv;
class KeyEnvPull extends Command
{
protected $signature = 'keyenv:pull
{--env= : KeyEnv environment (defaults to current APP_ENV)}
{--output=.env : Output file path}';
protected $description = 'Pull secrets from KeyEnv and write to .env file';
public function handle(): int
{
$token = config('keyenv.token');
$projectId = config('keyenv.project_id');
if (!$token || !$projectId) {
$this->error('KEYENV_TOKEN and KEYENV_PROJECT must be set');
return 1;
}
$environment = $this->option('env')
?? config('keyenv.environments.' . app()->environment())
?? app()->environment();
$output = $this->option('output');
$this->info("Pulling secrets from KeyEnv ({$environment})...");
try {
$client = KeyEnv::create($token);
$content = $client->generateEnvFile($projectId, $environment);
file_put_contents(base_path($output), $content);
$this->info("Secrets written to {$output}");
return 0;
} catch (\Exception $e) {
$this->error("Failed: {$e->getMessage()}");
return 1;
}
}
}
```
#### keyenv:env Command
```php
// app/Console/Commands/KeyEnvEnv.php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use KeyEnv\KeyEnv;
class KeyEnvEnv extends Command
{
protected $signature = 'keyenv:env
{--env= : KeyEnv environment to list}';
protected $description = 'List available KeyEnv environments';
public function handle(): int
{
$token = config('keyenv.token');
$projectId = config('keyenv.project_id');
if (!$token || !$projectId) {
$this->error('KEYENV_TOKEN and KEYENV_PROJECT must be set');
return 1;
}
try {
$client = KeyEnv::create($token);
$environments = $client->listEnvironments($projectId);
$this->table(
['Name', 'Inherits From'],
collect($environments)->map(fn($env) => [
$env->name,
$env->inheritsFrom ?? '-',
])
);
return 0;
} catch (\Exception $e) {
$this->error("Failed: {$e->getMessage()}");
return 1;
}
}
}
```
Register commands in `app/Console/Kernel.php` (Laravel 10) or they auto-register in Laravel 11:
```php
protected $commands = [
Commands\KeyEnvPull::class,
Commands\KeyEnvEnv::class,
];
```
### Complete Example
Here's a complete setup for a production Laravel application:
#### Service Provider
```php
// app/Providers/KeyEnvServiceProvider.php
namespace App\Providers;
use Illuminate\Support\ServiceProvider;
use KeyEnv\KeyEnv;
class KeyEnvServiceProvider extends ServiceProvider
{
public function register(): void
{
$this->mergeConfigFrom(__DIR__.'/../../config/keyenv.php', 'keyenv');
$this->app->singleton(KeyEnv::class, function () {
$token = config('keyenv.token');
if (!$token) {
return null;
}
return KeyEnv::create($token, config('keyenv.timeout', 30));
});
$this->loadSecrets();
}
protected function loadSecrets(): void
{
if (!config('keyenv.enabled')) {
return;
}
$token = config('keyenv.token');
$projectId = config('keyenv.project_id');
if (!$token || !$projectId) {
return;
}
try {
$client = KeyEnv::create($token, config('keyenv.timeout', 30));
$environment = $this->resolveEnvironment();
$client->loadEnv($projectId, $environment);
} catch (\Exception $e) {
// Log but don't crash - allows fallback to .env
logger()->error('KeyEnv: Failed to load secrets', [
'error' => $e->getMessage(),
]);
}
}
protected function resolveEnvironment(): string
{
// Explicit override
if ($env = env('KEYENV_ENV')) {
return $env;
}
// Map Laravel environment
$laravelEnv = app()->environment();
return config("keyenv.environments.{$laravelEnv}", $laravelEnv);
}
public function boot(): void
{
if ($this->app->runningInConsole()) {
$this->publishes([
__DIR__.'/../../config/keyenv.php' => config_path('keyenv.php'),
], 'keyenv-config');
}
}
}
```
#### Database Configuration
```php
// config/database.php
return [
'default' => env('DB_CONNECTION', 'pgsql'),
'connections' => [
'pgsql' => [
'driver' => 'pgsql',
'url' => env('DATABASE_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '5432'),
'database' => env('DB_DATABASE', 'forge'),
'username' => env('DB_USERNAME', 'forge'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8',
'prefix' => '',
'prefix_indexes' => true,
'search_path' => 'public',
'sslmode' => 'prefer',
],
'mysql' => [
'driver' => 'mysql',
'url' => env('DATABASE_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
'database' => env('DB_DATABASE', 'forge'),
'username' => env('DB_USERNAME', 'forge'),
'password' => env('DB_PASSWORD', ''),
'unix_socket' => env('DB_SOCKET', ''),
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
'prefix' => '',
'prefix_indexes' => true,
'strict' => true,
'engine' => null,
],
],
'redis' => [
'client' => env('REDIS_CLIENT', 'phpredis'),
'default' => [
'url' => env('REDIS_URL'),
'host' => env('REDIS_HOST', '127.0.0.1'),
'password' => env('REDIS_PASSWORD'),
'port' => env('REDIS_PORT', '6379'),
'database' => env('REDIS_DB', '0'),
],
'cache' => [
'url' => env('REDIS_URL'),
'host' => env('REDIS_HOST', '127.0.0.1'),
'password' => env('REDIS_PASSWORD'),
'port' => env('REDIS_PORT', '6379'),
'database' => env('REDIS_CACHE_DB', '1'),
],
],
];
```
#### Services Configuration
```php
// config/services.php
return [
'mailgun' => [
'domain' => env('MAILGUN_DOMAIN'),
'secret' => env('MAILGUN_SECRET'),
'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
],
'postmark' => [
'token' => env('POSTMARK_TOKEN'),
],
'ses' => [
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
],
'stripe' => [
'key' => env('STRIPE_KEY'),
'secret' => env('STRIPE_SECRET'),
'webhook' => [
'secret' => env('STRIPE_WEBHOOK_SECRET'),
'tolerance' => env('STRIPE_WEBHOOK_TOLERANCE', 300),
],
],
'pusher' => [
'app_id' => env('PUSHER_APP_ID'),
'app_key' => env('PUSHER_APP_KEY'),
'app_secret' => env('PUSHER_APP_SECRET'),
'app_cluster' => env('PUSHER_APP_CLUSTER'),
],
];
```
### Setting Up Your Deployment
#### Required Environment Variables
Set these in your deployment platform (not in KeyEnv):
| Variable | Description |
|----------|-------------|
| `KEYENV_TOKEN` | Your KeyEnv service token |
| `KEYENV_PROJECT` | Your KeyEnv project ID |
| `APP_ENV` | Laravel environment (production, staging, local) |
| `APP_KEY` | Laravel encryption key (optional if in KeyEnv) |
#### Secrets to Store in KeyEnv
Store these secrets in KeyEnv for each environment:
| Secret | Description | Example |
|--------|-------------|---------|
| `APP_KEY` | Laravel encryption key | `base64:...` |
| `DB_HOST` | Database host | `db.example.com` |
| `DB_PASSWORD` | Database password | `secure-password` |
| `REDIS_PASSWORD` | Redis password | `redis-password` |
| `MAIL_PASSWORD` | SMTP password | `smtp-password` |
| `STRIPE_SECRET` | Stripe secret key | `sk_live_...` |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook secret | `whsec_...` |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key | `...` |
| `PUSHER_APP_SECRET` | Pusher secret | `...` |
#### Generate Laravel App Key
```bash
php artisan key:generate --show
# Copy the output to KeyEnv as APP_KEY
```
### Local Development
For local development, you have several options:
#### Option 1: Use KeyEnv in Development
Set `KEYENV_TOKEN` and `KEYENV_PROJECT` in your `.env` file:
```bash
# .env
KEYENV_TOKEN=env_dev_...
KEYENV_PROJECT=your-project-id
KEYENV_ENABLED=true
```
#### Option 2: Pull to .env
Use the CLI or Artisan command to generate a local `.env`:
```bash
# Using CLI
keyenv pull --env development --output .env
# Using Artisan
php artisan keyenv:pull --env=development
```
#### Option 3: Disable KeyEnv Locally
Use a local `.env` file without KeyEnv:
```bash
# .env
KEYENV_ENABLED=false
DB_HOST=127.0.0.1
DB_PASSWORD=secret
# ... other local secrets
```
### Testing
For tests, disable KeyEnv by setting the environment variable:
```php
// phpunit.xml
```
Or in your test setup:
```php
// tests/TestCase.php
protected function setUp(): void
{
putenv('KEYENV_ENABLED=false');
parent::setUp();
}
```
### Troubleshooting
#### "KEYENV_TOKEN not set"
Ensure `KEYENV_TOKEN` is set in your deployment platform's environment variables (Forge, Vapor, Render, etc.).
#### "Project not found"
Verify `KEYENV_PROJECT` matches your project ID in the KeyEnv dashboard.
#### "Environment not found"
Check that the environment name exists in your KeyEnv project. Laravel's `local` environment maps to KeyEnv's `development` by default.
#### Config caching issues
When using `php artisan config:cache`, ensure KeyEnv secrets are loaded before caching:
```bash
# In deployment script
php artisan config:clear
# Secrets will be loaded fresh on next request
php artisan config:cache
```
#### Secrets not loading
1. Verify `KeyEnvServiceProvider` is registered and runs early
2. Check that `loadEnv()` runs before Laravel reads config
3. Verify the service token has read access to the environment
4. Check for typos in secret key names
#### Performance
`loadEnv()` makes a single API call at application boot. Secrets are cached in `$_ENV` for the lifetime of the request. There's no additional overhead after initialization.
For optimal performance with Laravel Octane or similar long-running processes, secrets remain cached in memory.
## Spring Boot Integration
Use KeyEnv with Spring Boot applications for secure secrets management.
Source: https://keyenv.dev/docs/sdks/spring-boot/
Integrate KeyEnv with your Spring Boot application to securely manage secrets like database credentials, API keys, and external service configurations.
### Features
- Auto-configuration with Spring Boot starter
- PropertySource integration for seamless `@Value` injection
- Environment-aware configuration via `spring.profiles.active`
- Type-safe `@ConfigurationProperties` binding
- Works with Spring Cloud Config
- Caching for optimal performance
### Installation
#### Maven
Add the JitPack repository and dependency to your `pom.xml`:
```xml
jitpack.iohttps://jitpack.iocom.github.keyenvjava-sdkv1.1.0
```
#### Gradle
```groovy
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.keyenv:java-sdk:v1.1.0'
}
```
### Quick Start
The simplest approach loads secrets into system properties at application startup:
```java
// Application.java
import dev.keyenv.KeyEnv;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import jakarta.annotation.PostConstruct;
@SpringBootApplication
public class Application {
@PostConstruct
public void loadSecrets() {
String token = System.getenv("KEYENV_TOKEN");
String projectId = System.getenv("KEYENV_PROJECT");
String environment = System.getenv("KEYENV_ENV");
if (token != null && projectId != null) {
KeyEnv client = KeyEnv.create(token);
int count = client.loadEnv(projectId, environment != null ? environment : "development");
System.out.println("Loaded " + count + " secrets from KeyEnv");
}
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
Now use secrets in your configuration:
```java
@Service
public class PaymentService {
@Value("${STRIPE_SECRET_KEY}")
private String stripeSecretKey;
// Use the secret...
}
```
### Application Configuration
#### application.properties
Configure your application using secrets loaded from KeyEnv:
```properties
# application.properties
# Database (values come from KeyEnv)
spring.datasource.url=${DATABASE_URL}
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}
# Redis
spring.data.redis.url=${REDIS_URL}
# External APIs
app.stripe.secret-key=${STRIPE_SECRET_KEY}
app.sendgrid.api-key=${SENDGRID_API_KEY}
```
#### application.yml
```yaml
# application.yml
spring:
datasource:
url: ${DATABASE_URL}
username: ${DB_USER}
password: ${DB_PASSWORD}
data:
redis:
url: ${REDIS_URL}
app:
stripe:
secret-key: ${STRIPE_SECRET_KEY}
sendgrid:
api-key: ${SENDGRID_API_KEY}
```
### Environment-Aware Configuration
#### Mapping Spring Profiles to KeyEnv Environments
Map `spring.profiles.active` to KeyEnv environments:
```java
import dev.keyenv.KeyEnv;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.core.env.Environment;
import jakarta.annotation.PostConstruct;
@SpringBootApplication
public class Application {
private final Environment springEnv;
public Application(Environment springEnv) {
this.springEnv = springEnv;
}
@PostConstruct
public void loadSecrets() {
String token = System.getenv("KEYENV_TOKEN");
String projectId = System.getenv("KEYENV_PROJECT");
if (token == null || projectId == null) {
return; // Skip in local development
}
// Map Spring profile to KeyEnv environment
String keyenvEnv = mapProfileToEnvironment();
KeyEnv client = KeyEnv.create(token);
client.loadEnv(projectId, keyenvEnv);
}
private String mapProfileToEnvironment() {
String[] profiles = springEnv.getActiveProfiles();
if (profiles.length == 0) {
return "development";
}
String profile = profiles[0];
return switch (profile) {
case "prod", "production" -> "production";
case "staging", "stage" -> "staging";
case "test", "testing" -> "testing";
default -> "development";
};
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
#### Profile-Specific Loading
Load different secrets based on Spring profiles:
```java
@Configuration
@Profile("!local") // Don't load from KeyEnv in local profile
public class KeyEnvConfig {
@Value("${spring.profiles.active:development}")
private String activeProfile;
@PostConstruct
public void loadSecrets() {
String token = System.getenv("KEYENV_TOKEN");
String projectId = System.getenv("KEYENV_PROJECT");
if (token != null && projectId != null) {
KeyEnv client = KeyEnv.create(token);
client.loadEnv(projectId, activeProfile);
}
}
}
```
### PropertySource Integration
#### Custom PropertySource
Create a custom PropertySource to integrate KeyEnv with Spring's property resolution:
```java
import dev.keyenv.KeyEnv;
import org.springframework.core.env.PropertySource;
import java.util.Map;
public class KeyEnvPropertySource extends PropertySource> {
public KeyEnvPropertySource(String name, Map source) {
super(name, source);
}
@Override
public Object getProperty(String name) {
return source.get(name);
}
public static KeyEnvPropertySource create(KeyEnv client, String projectId, String environment) {
Map secrets = client.exportSecretsAsMap(projectId, environment);
return new KeyEnvPropertySource("keyenv", secrets);
}
}
```
#### Register PropertySource Early
Register the PropertySource before Spring processes configuration:
```java
import dev.keyenv.KeyEnv;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ApplicationContextInitializer;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.core.env.ConfigurableEnvironment;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication app = new SpringApplication(Application.class);
app.addInitializers(new KeyEnvInitializer());
app.run(args);
}
}
class KeyEnvInitializer implements ApplicationContextInitializer {
@Override
public void initialize(ConfigurableApplicationContext context) {
String token = System.getenv("KEYENV_TOKEN");
String projectId = System.getenv("KEYENV_PROJECT");
String environment = System.getenv("KEYENV_ENV");
if (token == null || projectId == null) {
return;
}
KeyEnv client = KeyEnv.create(token);
KeyEnvPropertySource propertySource = KeyEnvPropertySource.create(
client,
projectId,
environment != null ? environment : "development"
);
ConfigurableEnvironment env = context.getEnvironment();
env.getPropertySources().addFirst(propertySource);
}
}
```
### ConfigurationProperties Binding
#### Type-Safe Configuration
Use `@ConfigurationProperties` for type-safe secret binding:
```java
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
private Stripe stripe = new Stripe();
private Database database = new Database();
private Redis redis = new Redis();
private SendGrid sendgrid = new SendGrid();
// Getters and setters...
public static class Stripe {
private String secretKey;
private String webhookSecret;
// Getters and setters...
public String getSecretKey() { return secretKey; }
public void setSecretKey(String secretKey) { this.secretKey = secretKey; }
public String getWebhookSecret() { return webhookSecret; }
public void setWebhookSecret(String webhookSecret) { this.webhookSecret = webhookSecret; }
}
public static class Database {
private String url;
private String username;
private String password;
// Getters and setters...
public String getUrl() { return url; }
public void setUrl(String url) { this.url = url; }
public String getUsername() { return username; }
public void setUsername(String username) { this.username = username; }
public String getPassword() { return password; }
public void setPassword(String password) { this.password = password; }
}
public static class Redis {
private String url;
private String password;
// Getters and setters...
public String getUrl() { return url; }
public void setUrl(String url) { this.url = url; }
public String getPassword() { return password; }
public void setPassword(String password) { this.password = password; }
}
public static class SendGrid {
private String apiKey;
public String getApiKey() { return apiKey; }
public void setApiKey(String apiKey) { this.apiKey = apiKey; }
}
// Root getters and setters
public Stripe getStripe() { return stripe; }
public void setStripe(Stripe stripe) { this.stripe = stripe; }
public Database getDatabase() { return database; }
public void setDatabase(Database database) { this.database = database; }
public Redis getRedis() { return redis; }
public void setRedis(Redis redis) { this.redis = redis; }
public SendGrid getSendgrid() { return sendgrid; }
public void setSendgrid(SendGrid sendgrid) { this.sendgrid = sendgrid; }
}
```
#### Mapping Secrets to Properties
In your `application.yml`, map KeyEnv secrets to configuration properties:
```yaml
# application.yml
app:
stripe:
secret-key: ${STRIPE_SECRET_KEY}
webhook-secret: ${STRIPE_WEBHOOK_SECRET}
database:
url: ${DATABASE_URL}
username: ${DB_USER}
password: ${DB_PASSWORD}
redis:
url: ${REDIS_URL}
password: ${REDIS_PASSWORD:}
sendgrid:
api-key: ${SENDGRID_API_KEY}
```
#### Using Configuration Properties
```java
@Service
public class PaymentService {
private final AppProperties properties;
public PaymentService(AppProperties properties) {
this.properties = properties;
}
public void processPayment() {
Stripe.apiKey = properties.getStripe().getSecretKey();
// Process payment...
}
}
```
### Complete Example
Here's a complete Spring Boot application with KeyEnv integration:
#### Project Structure
```
src/main/java/com/example/
├── Application.java
├── config/
│ ├── KeyEnvConfig.java
│ ├── KeyEnvPropertySource.java
│ └── AppProperties.java
├── service/
│ └── UserService.java
└── controller/
└── UserController.java
```
#### Application.java
```java
package com.example;
import com.example.config.KeyEnvPropertySource;
import dev.keyenv.KeyEnv;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.ApplicationContextInitializer;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.core.env.ConfigurableEnvironment;
@SpringBootApplication
@EnableConfigurationProperties
public class Application {
public static void main(String[] args) {
SpringApplication app = new SpringApplication(Application.class);
app.addInitializers(new KeyEnvInitializer());
app.run(args);
}
static class KeyEnvInitializer implements ApplicationContextInitializer {
@Override
public void initialize(ConfigurableApplicationContext context) {
String token = System.getenv("KEYENV_TOKEN");
String projectId = System.getenv("KEYENV_PROJECT");
if (token == null || projectId == null) {
System.out.println("KeyEnv not configured, using local environment");
return;
}
// Determine environment from Spring profile or KEYENV_ENV
ConfigurableEnvironment env = context.getEnvironment();
String keyenvEnv = System.getenv("KEYENV_ENV");
if (keyenvEnv == null) {
String[] profiles = env.getActiveProfiles();
keyenvEnv = profiles.length > 0 ? mapProfile(profiles[0]) : "development";
}
try {
KeyEnv client = KeyEnv.create(token);
var secrets = client.exportSecretsAsMap(projectId, keyenvEnv);
env.getPropertySources().addFirst(new KeyEnvPropertySource("keyenv", secrets));
System.out.println("Loaded " + secrets.size() + " secrets from KeyEnv (" + keyenvEnv + ")");
} catch (Exception e) {
System.err.println("Failed to load secrets from KeyEnv: " + e.getMessage());
}
}
private String mapProfile(String profile) {
return switch (profile) {
case "prod", "production" -> "production";
case "staging", "stage" -> "staging";
case "test" -> "testing";
default -> "development";
};
}
}
}
```
#### application.yml
```yaml
# application.yml
spring:
profiles:
active: ${SPRING_PROFILES_ACTIVE:development}
# Database
datasource:
url: ${DATABASE_URL:jdbc:postgresql://localhost:5432/myapp}
username: ${DB_USER:postgres}
password: ${DB_PASSWORD:}
driver-class-name: org.postgresql.Driver
hikari:
maximum-pool-size: 10
minimum-idle: 5
# JPA
jpa:
hibernate:
ddl-auto: validate
show-sql: false
# Redis
data:
redis:
url: ${REDIS_URL:redis://localhost:6379}
# Application secrets
app:
stripe:
secret-key: ${STRIPE_SECRET_KEY:}
webhook-secret: ${STRIPE_WEBHOOK_SECRET:}
publishable-key: ${STRIPE_PUBLISHABLE_KEY:}
sendgrid:
api-key: ${SENDGRID_API_KEY:}
jwt:
secret: ${JWT_SECRET:dev-secret-change-in-production}
expiration: 86400000
```
#### UserService.java
```java
package com.example.service;
import com.example.config.AppProperties;
import org.springframework.stereotype.Service;
@Service
public class UserService {
private final AppProperties properties;
public UserService(AppProperties properties) {
this.properties = properties;
}
public void sendWelcomeEmail(String email) {
// Use SendGrid API key from KeyEnv
String apiKey = properties.getSendgrid().getApiKey();
// Send email...
}
}
```
### Setting Up Your Deployment
#### Required Environment Variables
Set these in your deployment platform (not in KeyEnv):
| Variable | Description |
|----------|-------------|
| `KEYENV_TOKEN` | Your KeyEnv service token |
| `KEYENV_PROJECT` | Your KeyEnv project ID |
| `KEYENV_ENV` | KeyEnv environment (optional, derived from Spring profile) |
| `SPRING_PROFILES_ACTIVE` | Spring profile (production, staging, etc.) |
#### Secrets to Store in KeyEnv
Store these secrets in KeyEnv for each environment:
| Secret | Description | Example |
|--------|-------------|---------|
| `DATABASE_URL` | JDBC connection URL | `jdbc:postgresql://host:5432/db` |
| `DB_USER` | Database username | `myapp` |
| `DB_PASSWORD` | Database password | `secure-password` |
| `REDIS_URL` | Redis connection URL | `redis://localhost:6379` |
| `JWT_SECRET` | JWT signing secret | `your-256-bit-secret` |
| `STRIPE_SECRET_KEY` | Stripe API key | `sk_live_...` |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook secret | `whsec_...` |
| `SENDGRID_API_KEY` | SendGrid API key | `SG.xxx` |
### Docker Deployment
#### Dockerfile
```dockerfile
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY target/*.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]
```
#### docker-compose.yml
```yaml
version: '3.8'
services:
app:
build: .
environment:
- KEYENV_TOKEN=${KEYENV_TOKEN}
- KEYENV_PROJECT=${KEYENV_PROJECT}
- SPRING_PROFILES_ACTIVE=production
ports:
- "8080:8080"
```
### Local Development
#### Skip KeyEnv in Development
For local development, you can skip KeyEnv entirely:
```java
@PostConstruct
public void loadSecrets() {
String token = System.getenv("KEYENV_TOKEN");
if (token == null) {
System.out.println("KEYENV_TOKEN not set, using local configuration");
return;
}
// Load from KeyEnv...
}
```
#### Use .env File Locally
Generate a `.env` file for local development:
```bash
keyenv pull --env development --output .env
```
Load it with a library like [dotenv-java](https://github.com/cdimascio/dotenv-java):
```java
import io.github.cdimascio.dotenv.Dotenv;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
// Load .env in development
if (System.getenv("KEYENV_TOKEN") == null) {
Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
dotenv.entries().forEach(e ->
System.setProperty(e.getKey(), e.getValue())
);
}
SpringApplication.run(Application.class, args);
}
}
```
### Testing
#### Unit Tests
Mock the configuration properties in tests:
```java
@SpringBootTest
@TestPropertySource(properties = {
"app.stripe.secret-key=sk_test_xxx",
"app.jwt.secret=test-secret"
})
class PaymentServiceTest {
@Autowired
private PaymentService paymentService;
@Test
void shouldProcessPayment() {
// Test with mocked properties
}
}
```
#### Integration Tests
Use test-specific configuration:
```yaml
# application-test.yml
app:
stripe:
secret-key: sk_test_xxx
database:
url: jdbc:h2:mem:testdb
```
```java
@SpringBootTest
@ActiveProfiles("test")
class IntegrationTest {
// Tests run with test configuration, not KeyEnv
}
```
### Troubleshooting
#### "KEYENV_TOKEN not set"
In production, ensure `KEYENV_TOKEN` is set in your deployment platform's environment variables.
#### "Project not found"
Verify `KEYENV_PROJECT` matches your project ID in the KeyEnv dashboard.
#### "Environment not found"
Check that the environment name (development, staging, production) exists in your KeyEnv project.
#### Secrets not available in @Value
1. Ensure secrets are loaded before Spring processes `@Value` annotations (use `ApplicationContextInitializer`)
2. Check that the secret key matches exactly (case-sensitive)
3. Verify the service token has read access to the environment
#### DataSource fails to initialize
Database properties must be available before Spring creates the DataSource. Use the `ApplicationContextInitializer` approach to load secrets early enough.
#### Performance
Secrets are loaded once at startup and cached. There's no runtime API calls after initialization. For optimal performance in containerized environments, consider enabling caching:
```java
KeyEnv client = KeyEnv.builder()
.token(token)
.cacheTtl(Duration.ofMinutes(5))
.build();
```
## Rails Integration
Use KeyEnv with Ruby on Rails applications for secure secrets management.
Source: https://keyenv.dev/docs/sdks/rails/
Integrate KeyEnv with your Ruby on Rails application to securely manage secrets like database credentials, API keys, and Rails secret key base.
### Features
- Load secrets before Rails initializes
- Environment-aware configuration (development, test, production)
- Works with Rails credentials and encrypted secrets
- Supports database.yml, storage.yml, and other config files
- Built-in caching for serverless environments
### Installation
Add the KeyEnv gem to your Gemfile:
```ruby
# Gemfile
gem 'keyenv'
```
Then install:
```bash
bundle install
```
### Quick Start
Create an initializer to load secrets at boot:
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
require 'keyenv'
client = KeyEnv.new(token: ENV['KEYENV_TOKEN'])
client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: Rails.env
)
end
```
Now use secrets in your configuration:
```ruby
# config/application.rb
config.secret_key_base = ENV['SECRET_KEY_BASE']
```
### Rails Initializer Setup
#### Basic Initializer
The simplest approach loads all secrets into `ENV` at startup:
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
require 'keyenv'
# Map Rails.env to KeyEnv environment
keyenv_environment = case Rails.env
when 'development' then 'development'
when 'test' then 'development'
when 'staging' then 'staging'
when 'production' then 'production'
else Rails.env
end
client = KeyEnv.new(token: ENV['KEYENV_TOKEN'])
count = client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: keyenv_environment
)
Rails.logger.info "KeyEnv: Loaded #{count} secrets for #{keyenv_environment}" if defined?(Rails.logger)
end
```
#### With Caching (Serverless)
For serverless environments like AWS Lambda, enable caching:
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
require 'keyenv'
client = KeyEnv.new(
token: ENV['KEYENV_TOKEN'],
cache_ttl: 300 # Cache for 5 minutes
)
client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: Rails.env
)
end
```
#### Early Loading with boot.rb
For secrets needed before initializers run (like database credentials), load in `boot.rb`:
```ruby
# config/boot.rb
ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
require 'bundler/setup'
require 'bootsnap/setup' if defined?(Bootsnap)
# Load KeyEnv secrets before Rails initializes
if ENV['KEYENV_TOKEN'].present?
require 'keyenv'
rails_env = ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
client = KeyEnv.new(token: ENV['KEYENV_TOKEN'])
client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: rails_env
)
end
```
### Environment-Aware Configuration
#### Automatic Environment Detection
Map Rails environments to KeyEnv environments:
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
require 'keyenv'
def detect_keyenv_environment
# Check explicit override first
return ENV['KEYENV_ENV'] if ENV['KEYENV_ENV'].present?
# Map Rails.env to KeyEnv environment
case Rails.env
when 'development', 'test'
'development'
when 'staging', 'review'
'staging'
when 'production'
'production'
else
Rails.env
end
end
client = KeyEnv.new(token: ENV['KEYENV_TOKEN'])
client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: detect_keyenv_environment
)
end
```
#### Platform-Specific Detection
Detect environment from deployment platforms:
```ruby
# config/initializers/keyenv.rb
def detect_keyenv_environment
return ENV['KEYENV_ENV'] if ENV['KEYENV_ENV'].present?
# Heroku
if ENV['HEROKU_APP_NAME'].present?
return ENV['HEROKU_APP_NAME'].include?('staging') ? 'staging' : 'production'
end
# Render
return 'production' if ENV['RENDER'].present?
# Railway
return ENV['RAILWAY_ENVIRONMENT'] if ENV['RAILWAY_ENVIRONMENT'].present?
# Fly.io
return 'production' if ENV['FLY_APP_NAME'].present?
# Fall back to Rails.env mapping
case Rails.env
when 'development', 'test' then 'development'
when 'staging' then 'staging'
else 'production'
end
end
```
### Database Configuration
#### Using database.yml with ERB
Reference secrets in `database.yml`:
```yaml
# config/database.yml
default: &default
adapter: postgresql
encoding: unicode
pool: <%= ENV.fetch("DB_POOL", 5) %>
development:
<<: *default
database: myapp_development
test:
<<: *default
database: myapp_test
production:
<<: *default
url: <%= ENV['DATABASE_URL'] %>
```
Store in KeyEnv:
```
DATABASE_URL=postgres://user:password@host:5432/myapp_production
DB_POOL=25
```
#### Individual Database Credentials
For more control, use individual variables:
```yaml
# config/database.yml
production:
adapter: postgresql
encoding: unicode
host: <%= ENV['DB_HOST'] %>
port: <%= ENV.fetch('DB_PORT', 5432) %>
database: <%= ENV['DB_NAME'] %>
username: <%= ENV['DB_USER'] %>
password: <%= ENV['DB_PASSWORD'] %>
pool: <%= ENV.fetch('DB_POOL', 5) %>
```
Store in KeyEnv:
```
DB_HOST=your-db-host.amazonaws.com
DB_PORT=5432
DB_NAME=myapp_production
DB_USER=myapp
DB_PASSWORD=secure-password
```
### Storage Configuration
#### Active Storage with S3
```yaml
# config/storage.yml
amazon:
service: S3
access_key_id: <%= ENV['AWS_ACCESS_KEY_ID'] %>
secret_access_key: <%= ENV['AWS_SECRET_ACCESS_KEY'] %>
region: <%= ENV.fetch('AWS_REGION', 'us-east-1') %>
bucket: <%= ENV['AWS_S3_BUCKET'] %>
```
Store in KeyEnv:
```
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=secret...
AWS_REGION=us-east-1
AWS_S3_BUCKET=myapp-production
```
#### Active Storage with Google Cloud
```yaml
# config/storage.yml
google:
service: GCS
project: <%= ENV['GCS_PROJECT'] %>
credentials: <%= ENV['GCS_CREDENTIALS'] %>
bucket: <%= ENV['GCS_BUCKET'] %>
```
### Rails Credentials Integration
#### Hybrid Approach
Use KeyEnv for deployment secrets and Rails credentials for development:
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
require 'keyenv'
client = KeyEnv.new(token: ENV['KEYENV_TOKEN'])
client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: Rails.env
)
else
# Fall back to Rails credentials in development
Rails.logger.info 'KeyEnv: Using Rails credentials (KEYENV_TOKEN not set)'
end
```
#### Accessing Secrets
Create a helper that checks ENV first, then falls back to credentials:
```ruby
# config/initializers/secrets.rb
module Secrets
class << self
def fetch(key, default = nil)
ENV[key.to_s.upcase] || Rails.application.credentials.dig(key) || default
end
def [](key)
fetch(key)
end
end
end
```
Usage:
```ruby
Secrets.fetch(:stripe_secret_key)
Secrets[:aws_access_key_id]
```
### Configuration Patterns
#### Action Mailer
```ruby
# config/environments/production.rb
config.action_mailer.smtp_settings = {
address: ENV.fetch('SMTP_HOST', 'smtp.gmail.com'),
port: ENV.fetch('SMTP_PORT', 587).to_i,
user_name: ENV['SMTP_USERNAME'],
password: ENV['SMTP_PASSWORD'],
authentication: :plain,
enable_starttls_auto: true
}
```
#### Redis / Sidekiq
```ruby
# config/initializers/sidekiq.rb
Sidekiq.configure_server do |config|
config.redis = { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }
end
Sidekiq.configure_client do |config|
config.redis = { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }
end
```
#### Action Cable
```ruby
# config/cable.yml
production:
adapter: redis
url: <%= ENV.fetch('REDIS_URL', 'redis://localhost:6379/1') %>
channel_prefix: myapp_production
```
### Complete Example
Here's a complete Rails configuration using KeyEnv:
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
require 'keyenv'
KEYENV_ENV_MAP = {
'development' => 'development',
'test' => 'development',
'staging' => 'staging',
'production' => 'production'
}.freeze
keyenv_env = ENV.fetch('KEYENV_ENV') { KEYENV_ENV_MAP.fetch(Rails.env, Rails.env) }
begin
client = KeyEnv.new(
token: ENV['KEYENV_TOKEN'],
timeout: 10,
cache_ttl: Rails.env.production? ? 300 : 0
)
count = client.load_env(
project_id: ENV['KEYENV_PROJECT'],
environment: keyenv_env
)
Rails.logger.info "KeyEnv: Loaded #{count} secrets for #{keyenv_env}" if defined?(Rails.logger)
rescue KeyEnv::Error => e
Rails.logger.error "KeyEnv: Failed to load secrets - #{e.message}" if defined?(Rails.logger)
raise if Rails.env.production? # Fail hard in production
end
end
```
```yaml
# config/database.yml
default: &default
adapter: postgresql
encoding: unicode
pool: <%= ENV.fetch("DB_POOL", 5) %>
development:
<<: *default
database: myapp_development
test:
<<: *default
database: myapp_test
production:
<<: *default
url: <%= ENV['DATABASE_URL'] %>
```
```ruby
# config/environments/production.rb
Rails.application.configure do
# Secret key base
config.secret_key_base = ENV['SECRET_KEY_BASE']
# Force SSL
config.force_ssl = true
# Action Mailer
config.action_mailer.smtp_settings = {
address: ENV['SMTP_HOST'],
port: ENV.fetch('SMTP_PORT', 587).to_i,
user_name: ENV['SMTP_USERNAME'],
password: ENV['SMTP_PASSWORD'],
authentication: :plain,
enable_starttls_auto: true
}
# Logging
config.log_level = ENV.fetch('LOG_LEVEL', 'info').to_sym
end
```
```ruby
# config/initializers/stripe.rb
Stripe.api_key = ENV['STRIPE_SECRET_KEY']
```
```ruby
# config/initializers/sentry.rb
if ENV['SENTRY_DSN'].present?
Sentry.init do |config|
config.dsn = ENV['SENTRY_DSN']
config.environment = Rails.env
config.traces_sample_rate = 0.1
end
end
```
### Setting Up Your Deployment
#### Required Environment Variables
Set these in your deployment platform (not in KeyEnv):
| Variable | Description |
|----------|-------------|
| `KEYENV_TOKEN` | Your KeyEnv service token |
| `KEYENV_PROJECT` | Your KeyEnv project ID |
| `KEYENV_ENV` | Override environment detection (optional) |
#### Secrets to Store in KeyEnv
Store these secrets in KeyEnv for each environment:
| Secret | Description | Example |
|--------|-------------|---------|
| `SECRET_KEY_BASE` | Rails secret key | `rails secret` output |
| `DATABASE_URL` | Database connection | `postgres://user:pass@host/db` |
| `REDIS_URL` | Redis connection | `redis://localhost:6379/0` |
| `SMTP_PASSWORD` | Email password | `app-specific-password` |
| `AWS_ACCESS_KEY_ID` | AWS credentials | `AKIA...` |
| `AWS_SECRET_ACCESS_KEY` | AWS secret | `...` |
| `STRIPE_SECRET_KEY` | Stripe API key | `sk_live_...` |
| `SENTRY_DSN` | Sentry DSN | `https://...@sentry.io/...` |
#### Generate a Rails Secret Key
```bash
rails secret
```
### Local Development
#### Without KeyEnv
For local development without KeyEnv, the initializer gracefully skips loading:
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
# ... KeyEnv loading
end
# Falls back to local environment variables or Rails credentials
```
#### Using the CLI
Generate a `.env` file for local development:
```bash
keyenv pull --env development --output .env
```
Then use dotenv to load it:
```ruby
# Gemfile (development group)
group :development, :test do
gem 'dotenv-rails'
end
```
The dotenv gem loads `.env` automatically before Rails initializers.
### Testing
#### Test Environment Setup
Skip KeyEnv in tests by not setting `KEYENV_TOKEN`:
```ruby
# spec/rails_helper.rb
# Test environment variables
ENV['SECRET_KEY_BASE'] = 'test-secret-key-base'
ENV['DATABASE_URL'] = 'postgres://localhost/myapp_test'
```
Or use a separate test environment in KeyEnv:
```ruby
# config/initializers/keyenv.rb
keyenv_env = case Rails.env
when 'test' then 'test' # Use KeyEnv test environment
# ...
end
```
#### RSpec Configuration
```ruby
# spec/support/keyenv.rb
RSpec.configure do |config|
config.before(:suite) do
# Ensure test secrets are available
ENV['SECRET_KEY_BASE'] ||= 'test-secret'
ENV['STRIPE_SECRET_KEY'] ||= 'sk_test_fake'
end
end
```
### Troubleshooting
#### "KEYENV_TOKEN not set"
In production, ensure `KEYENV_TOKEN` is set in your deployment platform's environment variables.
#### "Project not found"
Verify `KEYENV_PROJECT` matches your project ID in the KeyEnv dashboard.
#### "Environment not found"
Check that the environment name exists in your KeyEnv project and matches your Rails environment mapping.
#### Secrets not loading in database.yml
If database credentials aren't available when Rails initializes:
1. Move KeyEnv loading to `config/boot.rb` (before database.yml is processed)
2. Or use `DATABASE_URL` which Rails handles specially
#### Debugging
Enable debug logging:
```ruby
# config/initializers/keyenv.rb
if ENV['KEYENV_TOKEN'].present?
require 'keyenv'
client = KeyEnv.new(token: ENV['KEYENV_TOKEN'])
begin
secrets = client.export_secrets(
project_id: ENV['KEYENV_PROJECT'],
environment: Rails.env
)
Rails.logger.debug "KeyEnv: Found #{secrets.count} secrets"
secrets.each { |s| Rails.logger.debug "KeyEnv: - #{s.key}" }
client.load_env(project_id: ENV['KEYENV_PROJECT'], environment: Rails.env)
rescue KeyEnv::Error => e
Rails.logger.error "KeyEnv: #{e.class} - #{e.message}"
raise
end
end
```
#### Performance
`load_env` makes a single API call at startup. Secrets are cached in `ENV` for the lifetime of the process. There's no runtime overhead after initialization.
For serverless environments, use `cache_ttl` to avoid repeated API calls on warm starts.
## GitHub Action
Inject KeyEnv secrets into GitHub Actions workflows.
Source: https://keyenv.dev/docs/sdks/github-action/
Fetch secrets from KeyEnv and inject them into your GitHub Actions workflows.
### Features
- Exports secrets as environment variables
- Optionally writes secrets to a `.env` file
- Automatically masks secret values in logs
- Supports project-scoped service tokens
- Zero dependencies (uses pre-installed tools)
### Basic Usage
```yaml
steps:
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: production
- run: echo "Database is at $DATABASE_URL"
```
### Inputs
| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `token` | KeyEnv service token | Yes | - |
| `environment` | Environment name (e.g., `production`) | Yes | - |
| `project-id` | Project ID. Optional if using project-scoped token. | No | - |
| `api-url` | KeyEnv API URL | No | `https://api.keyenv.dev` |
| `export-env` | Export secrets to `$GITHUB_ENV` | No | `true` |
| `env-file` | Path to write `.env` file | No | - |
| `mask-values` | Mask secret values in logs | No | `true` |
### Outputs
| Output | Description |
|--------|-------------|
| `count` | Number of secrets fetched |
### Examples
#### With Project ID
If your service token isn't project-scoped, specify the project:
```yaml
steps:
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
project-id: proj_abc123def456
environment: staging
```
#### Write to .env File
```yaml
steps:
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: production
env-file: .env
- run: |
# Secrets are now in .env file
source .env
./run-tests.sh
```
#### Disable Environment Export
If you only want the `.env` file without exporting to `$GITHUB_ENV`:
```yaml
steps:
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: production
export-env: false
env-file: .env
```
#### Deploy to Production
```yaml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: production
- run: ./deploy.sh
# All secrets are available as env vars
```
#### Multi-Environment Matrix
Test across all environments:
```yaml
name: Test All Environments
on: [push]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
environment: [development, staging, production]
steps:
- uses: actions/checkout@v4
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: ${{ matrix.environment }}
- run: npm test
```
#### Docker Build with Secrets
```yaml
name: Build Docker Image
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: production
env-file: .env.production
export-env: false
- run: |
docker build \
--secret id=env,src=.env.production \
-t myapp:latest .
```
#### Use Output Count
```yaml
steps:
- uses: keyenv/keyenv-action@v1
id: secrets
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: production
- run: echo "Loaded ${{ steps.secrets.outputs.count }} secrets"
```
#### Node.js Application
```yaml
name: CI
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: development
- run: npm ci
- run: npm test
- run: npm run build
```
#### Python Application
```yaml
name: CI
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: development
- run: pip install -r requirements.txt
- run: pytest
```
### Setting Up Your Token
1. Go to your KeyEnv dashboard
2. Navigate to **Settings > Service Tokens**
3. Create a new token with:
- **Scope**: Select your project (recommended)
- **Permissions**: `secrets:read`
4. Add the token to your GitHub repository:
- Go to **Settings > Secrets and variables > Actions**
- Click **New repository secret**
- Name: `KEYENV_TOKEN`
- Value: Your service token
### Security
- All secret values are automatically masked in GitHub Actions logs
- The service token is masked immediately upon use
- Secrets are fetched over HTTPS
- Service tokens can be scoped to specific projects and environments
### Self-Hosted KeyEnv
If you're running a self-hosted KeyEnv instance:
```yaml
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: production
api-url: https://keyenv.your-company.com
```
### Troubleshooting
#### "Authentication failed"
- Verify your token is correct
- Check the token hasn't expired
- Ensure the token is stored in GitHub Secrets correctly
#### "Access denied"
- The token may not have access to the specified project
- The token may not have access to the specified environment
- Check token permissions in KeyEnv dashboard
#### "Project or environment not found"
- Verify the `project-id` is correct
- Verify the `environment` name matches exactly (case-sensitive)
- Check the project/environment exists in KeyEnv
## Secret Scanner Action
Scan your codebase for hardcoded secrets in GitHub Actions.
Source: https://keyenv.dev/docs/sdks/scan-action/
Scan your codebase for hardcoded secrets before they reach production. This GitHub Action integrates KeyEnv's secret scanning directly into your CI/CD pipeline.
### Features
- Detect API keys, tokens, passwords, and other secrets
- 149+ patterns covering major providers (AWS, GitHub, Stripe, etc.)
- Configurable severity thresholds
- Cross-platform support (Linux, macOS)
- Optional upload to KeyEnv dashboard
- JSON output for downstream processing
### Basic Usage
Add to your workflow to scan for secrets on every push:
```yaml
name: Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Scan for secrets
uses: keyenv/scan-action@v1
```
### Inputs
| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `severity` | Minimum severity to fail (`critical`, `high`, `medium`, `low`) | No | `medium` |
| `path` | Path to scan | No | `.` |
| `upload` | Upload results to KeyEnv dashboard | No | `false` |
| `token` | KeyEnv service token (required if upload is true) | No | - |
| `version` | KeyEnv CLI version to use | No | `latest` |
### Outputs
| Output | Description |
|--------|-------------|
| `findings-count` | Number of secrets found |
| `findings-json` | JSON object containing all findings and summary |
### Examples
#### Custom Severity Threshold
Only fail on critical and high severity findings:
```yaml
- name: Scan for secrets
uses: keyenv/scan-action@v1
with:
severity: high
```
#### Scan Specific Directory
Scan only a specific directory:
```yaml
- name: Scan for secrets
uses: keyenv/scan-action@v1
with:
path: ./src
severity: medium
```
#### Upload to KeyEnv Dashboard
Upload scan results to your KeyEnv dashboard for tracking and reporting:
```yaml
- name: Scan for secrets
uses: keyenv/scan-action@v1
with:
upload: true
token: ${{ secrets.KEYENV_TOKEN }}
```
#### Use Findings in Subsequent Steps
Access scan results in downstream steps:
```yaml
- name: Scan for secrets
id: scan
uses: keyenv/scan-action@v1
continue-on-error: true
- name: Process results
if: steps.scan.outputs.findings-count > 0
run: |
echo "Found ${{ steps.scan.outputs.findings-count }} secrets"
echo "${{ steps.scan.outputs.findings-json }}" | jq '.findings[]'
```
#### Pin to Specific CLI Version
Use a specific version of the KeyEnv CLI:
```yaml
- name: Scan for secrets
uses: keyenv/scan-action@v1
with:
version: v0.5.0
```
### Complete Workflow Example
```yaml
name: Security
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
secret-scan:
name: Secret Scanning
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for better detection
- name: Scan for secrets
id: scan
uses: keyenv/scan-action@v1
with:
severity: high
upload: true
token: ${{ secrets.KEYENV_TOKEN }}
- name: Comment on PR
if: failure() && github.event_name == 'pull_request'
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '## Secret Scan Failed\n\nSecrets were detected in this PR. Please remove them before merging.\n\nFound: ${{ steps.scan.outputs.findings-count }} secrets'
})
```
### Severity Levels
- **critical**: Highly sensitive secrets (production API keys, private keys)
- **high**: Sensitive credentials (database passwords, OAuth tokens)
- **medium**: Potentially sensitive data (internal API keys)
- **low**: Low-risk findings (generic patterns that may be false positives)
### What Gets Detected
The scanner detects secrets from:
| Category | Examples |
|----------|----------|
| Cloud Providers | AWS access keys, GCP service accounts, Azure credentials |
| Version Control | GitHub PATs, GitLab tokens, Bitbucket app passwords |
| AI Services | OpenAI, Anthropic, Google AI API keys |
| Payments | Stripe, PayPal, Square API keys |
| Communication | Slack, Discord, Telegram tokens |
| Databases | Connection strings, MongoDB URIs, Redis passwords |
| Infrastructure | Terraform tokens, Kubernetes secrets, SSH keys |
| Generic | JWT tokens, API keys, passwords in URLs |
### Best Practices
1. **Run on pull requests**: Catch secrets before they're merged
2. **Use `severity: high`**: Reduce false positives in CI
3. **Upload results**: Track security trends over time
4. **Store tokens securely**: Use GitHub Secrets for your KeyEnv token
5. **Block merges**: Use required status checks to prevent secret leaks
### Difference from keyenv-action
KeyEnv provides two GitHub Actions:
| Action | Purpose |
|--------|---------|
| `keyenv/keyenv-action` | **Fetch secrets** - Inject KeyEnv secrets into your workflow |
| `keyenv/scan-action` | **Find secrets** - Scan for hardcoded secrets in your codebase |
Use them together for comprehensive secret management:
```yaml
jobs:
security:
runs-on: ubuntu-latest
steps:
# First, scan for any hardcoded secrets
- uses: actions/checkout@v4
- uses: keyenv/scan-action@v1
with:
severity: high
deploy:
needs: security
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Then, inject managed secrets for deployment
- uses: keyenv/keyenv-action@v1
with:
token: ${{ secrets.KEYENV_TOKEN }}
environment: production
- run: ./deploy.sh
```
## Bitbucket Pipelines
Inject KeyEnv secrets into Bitbucket Pipelines workflows.
Source: https://keyenv.dev/docs/sdks/bitbucket-pipelines/
Fetch secrets from KeyEnv and inject them into your Bitbucket Pipelines workflows.
### Features
- Exports secrets as environment variables
- Optionally writes secrets to a `.env` file
- Automatically masks secret values in logs
- Supports project-scoped service tokens
- Works with all Bitbucket plan tiers
### Basic Usage
```yaml
# bitbucket-pipelines.yml
pipelines:
default:
- step:
name: Build and Test
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: development
- npm ci
- npm test
```
### Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `KEYENV_TOKEN` | KeyEnv service token | Yes | - |
| `ENVIRONMENT` | Environment name (e.g., `production`) | Yes | - |
| `PROJECT_ID` | Project ID. Optional if using project-scoped token. | No | - |
| `API_URL` | KeyEnv API URL | No | `https://api.keyenv.dev` |
| `ENV_FILE` | Path to write `.env` file | No | - |
### Examples
#### With Project ID
If your service token isn't project-scoped, specify the project:
```yaml
pipelines:
default:
- step:
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
PROJECT_ID: proj_abc123def456
ENVIRONMENT: staging
- npm test
```
#### Write to .env File
```yaml
pipelines:
default:
- step:
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: production
ENV_FILE: .env
- source .env
- ./run-tests.sh
```
#### Deploy to Production
```yaml
pipelines:
branches:
main:
- step:
name: Deploy
deployment: production
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: production
- ./deploy.sh
```
#### Multi-Environment Deployment
```yaml
pipelines:
branches:
develop:
- step:
name: Deploy to Staging
deployment: staging
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: staging
- ./deploy.sh
main:
- step:
name: Deploy to Production
deployment: production
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: production
- ./deploy.sh
```
#### Docker Build
```yaml
pipelines:
default:
- step:
name: Build Docker Image
services:
- docker
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: production
ENV_FILE: .env.production
- docker build --secret id=env,src=.env.production -t myapp:latest .
- docker push myapp:latest
```
#### Node.js Application
```yaml
pipelines:
default:
- step:
name: Test
caches:
- node
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: development
- npm ci
- npm test
- npm run build
```
#### Python Application
```yaml
pipelines:
default:
- step:
name: Test
caches:
- pip
script:
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: development
- pip install -r requirements.txt
- pytest
```
### Setting Up Your Token
1. Go to your KeyEnv dashboard
2. Navigate to **Settings > Service Tokens**
3. Create a new token with:
- **Scope**: Select your project (recommended)
- **Permissions**: `secrets:read`
4. Add the token to your Bitbucket repository:
- Go to **Repository settings > Pipelines > Repository variables**
- Add a variable named `KEYENV_TOKEN`
- Check **Secured** to mask the value in logs
### Security
- All secret values are automatically masked in Bitbucket Pipelines logs
- The service token is secured and never exposed
- Secrets are fetched over HTTPS
- Service tokens can be scoped to specific projects and environments
### Self-Hosted KeyEnv
If you're running a self-hosted KeyEnv instance:
```yaml
- pipe: keyenv/keyenv-pipe:1.0.0
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
ENVIRONMENT: production
API_URL: https://keyenv.your-company.com
```
### Troubleshooting
#### "Authentication failed"
- Verify your token is correct
- Check the token hasn't expired
- Ensure the token is stored in Repository Variables correctly
#### "Access denied"
- The token may not have access to the specified project
- The token may not have access to the specified environment
- Check token permissions in KeyEnv dashboard
#### "Project or environment not found"
- Verify the `PROJECT_ID` is correct
- Verify the `ENVIRONMENT` name matches exactly (case-sensitive)
- Check the project/environment exists in KeyEnv
## AWS Lambda Layer
Pre-built Lambda Layer that fetches secrets from KeyEnv at cold start.
Source: https://keyenv.dev/docs/sdks/aws-lambda/
Pre-built Lambda Layer that automatically fetches secrets from KeyEnv and injects them into your Lambda function's environment variables.
### Features
- Fetches secrets once at cold start (minimal latency impact)
- Caches secrets in memory for warm invocations
- Supports Node.js 18/20 and Python 3.9/3.10/3.11/3.12
- Automatic retry with exponential backoff
- Falls back to existing env vars if KeyEnv is unreachable
- Zero code changes required
### Layer ARN
```
arn:aws:lambda::123456789012:layer:keyenv:
```
Available in all AWS regions. Replace `` with your region (e.g., `us-east-1`).
### Quick Start
1. Add the KeyEnv layer to your Lambda function
2. Set environment variables:
- `KEYENV_TOKEN`: Your service token
- `KEYENV_ENVIRONMENT`: Environment name (e.g., `production`)
3. Deploy - secrets are automatically loaded
### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `KEYENV_TOKEN` | KeyEnv service token | Yes | - |
| `KEYENV_ENVIRONMENT` | Environment name | Yes | - |
| `KEYENV_PROJECT_ID` | Project ID. Optional if using project-scoped token. | No | - |
| `KEYENV_API_URL` | KeyEnv API URL | No | `https://api.keyenv.dev` |
| `KEYENV_CACHE_TTL` | Cache TTL in seconds (0 = cache forever) | No | `0` |
### Examples
#### AWS Console
1. Open your Lambda function in the AWS Console
2. Go to **Layers** > **Add a layer**
3. Choose **Specify an ARN**
4. Enter: `arn:aws:lambda:us-east-1:123456789012:layer:keyenv:1`
5. Add environment variables in **Configuration > Environment variables**
#### Serverless Framework
```yaml
# serverless.yml
service: my-service
provider:
name: aws
runtime: nodejs20.x
layers:
- arn:aws:lambda:${aws:region}:123456789012:layer:keyenv:1
environment:
KEYENV_TOKEN: ${ssm:/keyenv/token}
KEYENV_ENVIRONMENT: ${opt:stage, 'development'}
functions:
api:
handler: handler.main
events:
- http:
path: /
method: get
```
#### AWS SAM
```yaml
# template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Globals:
Function:
Runtime: nodejs20.x
Layers:
- arn:aws:lambda:!Ref AWS::Region:123456789012:layer:keyenv:1
Environment:
Variables:
KEYENV_TOKEN: !Ref KeyEnvToken
KEYENV_ENVIRONMENT: !Ref Environment
Parameters:
KeyEnvToken:
Type: AWS::SSM::Parameter::Value
Default: /keyenv/token
Environment:
Type: String
Default: development
Resources:
ApiFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
CodeUri: ./src
Events:
Api:
Type: Api
Properties:
Path: /
Method: GET
```
#### Terraform
```hcl
# main.tf
resource "aws_lambda_function" "api" {
function_name = "my-api"
runtime = "nodejs20.x"
handler = "index.handler"
filename = "function.zip"
layers = [
"arn:aws:lambda:${var.region}:123456789012:layer:keyenv:1"
]
environment {
variables = {
KEYENV_TOKEN = var.keyenv_token
KEYENV_ENVIRONMENT = var.environment
}
}
}
variable "region" {
default = "us-east-1"
}
variable "keyenv_token" {
sensitive = true
}
variable "environment" {
default = "development"
}
```
#### AWS CDK (TypeScript)
```typescript
import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class MyStack extends cdk.Stack {
constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const keyenvLayer = lambda.LayerVersion.fromLayerVersionArn(
this, 'KeyEnvLayer',
`arn:aws:lambda:${this.region}:123456789012:layer:keyenv:1`
);
new lambda.Function(this, 'ApiFunction', {
runtime: lambda.Runtime.NODEJS_20_X,
handler: 'index.handler',
code: lambda.Code.fromAsset('src'),
layers: [keyenvLayer],
environment: {
KEYENV_TOKEN: process.env.KEYENV_TOKEN!,
KEYENV_ENVIRONMENT: 'production',
},
});
}
}
```
#### AWS CDK (Python)
```python
from aws_cdk import (
Stack,
aws_lambda as lambda_,
)
from constructs import Construct
class MyStack(Stack):
def __init__(self, scope: Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
keyenv_layer = lambda_.LayerVersion.from_layer_version_arn(
self, "KeyEnvLayer",
f"arn:aws:lambda:{self.region}:123456789012:layer:keyenv:1"
)
lambda_.Function(
self, "ApiFunction",
runtime=lambda_.Runtime.PYTHON_3_12,
handler="index.handler",
code=lambda_.Code.from_asset("src"),
layers=[keyenv_layer],
environment={
"KEYENV_TOKEN": os.environ["KEYENV_TOKEN"],
"KEYENV_ENVIRONMENT": "production",
},
)
```
#### Pulumi (TypeScript)
```typescript
import * as aws from "@pulumi/aws";
const keyenvLayerArn = `arn:aws:lambda:${aws.config.region}:123456789012:layer:keyenv:1`;
const apiFunction = new aws.lambda.Function("api", {
runtime: "nodejs20.x",
handler: "index.handler",
code: new pulumi.asset.FileArchive("./src"),
layers: [keyenvLayerArn],
environment: {
variables: {
KEYENV_TOKEN: config.requireSecret("keyenvToken"),
KEYENV_ENVIRONMENT: "production",
},
},
});
```
### How It Works
1. **Cold Start**: When Lambda initializes, the layer's extension runs first
2. **Fetch Secrets**: The extension calls KeyEnv API to fetch secrets
3. **Inject**: Secrets are injected into the process environment variables
4. **Your Code Runs**: Your handler sees secrets as regular env vars
5. **Warm Invocations**: Cached secrets are reused (no API call)
```
┌─────────────────────────────────────────────────────┐
│ Cold Start │
├─────────────────────────────────────────────────────┤
│ 1. Lambda Runtime Initializes │
│ 2. KeyEnv Layer Extension Runs │
│ └─> Fetches secrets from KeyEnv API │
│ └─> Injects into process.env │
│ 3. Your Handler Initializes │
│ 4. Handler Invoked │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│ Warm Invocation │
├─────────────────────────────────────────────────────┤
│ 1. Handler Invoked (secrets already in process.env)│
└─────────────────────────────────────────────────────┘
```
### Performance
| Scenario | Latency Impact |
|----------|---------------|
| Cold start (first invocation) | +50-150ms |
| Warm invocation | 0ms (cached) |
| KeyEnv unreachable | 0ms (fallback to existing env vars) |
The layer is optimized for minimal cold start impact:
- Single HTTP request to KeyEnv API
- Response caching for warm invocations
- Graceful fallback if API is unreachable
### Using Secrets in Your Code
#### Node.js
```javascript
// Secrets are automatically available in process.env
export const handler = async (event) => {
const databaseUrl = process.env.DATABASE_URL;
const apiKey = process.env.API_KEY;
// Use secrets normally
const db = await connectToDatabase(databaseUrl);
return {
statusCode: 200,
body: JSON.stringify({ message: 'Hello!' }),
};
};
```
#### Python
```python
import os
def handler(event, context):
# Secrets are automatically available in os.environ
database_url = os.environ['DATABASE_URL']
api_key = os.environ['API_KEY']
# Use secrets normally
db = connect_to_database(database_url)
return {
'statusCode': 200,
'body': json.dumps({'message': 'Hello!'})
}
```
### Cache TTL
By default, secrets are cached forever for the lifetime of the Lambda instance. To refresh secrets periodically:
```yaml
# serverless.yml
environment:
KEYENV_CACHE_TTL: "300" # Refresh every 5 minutes
```
| TTL Value | Behavior |
|-----------|----------|
| `0` (default) | Cache forever (best performance) |
| `300` | Refresh every 5 minutes |
| `3600` | Refresh every hour |
### Setting Up Your Token
1. Go to your KeyEnv dashboard
2. Navigate to **Settings > Service Tokens**
3. Create a new token with:
- **Scope**: Select your project (recommended)
- **Permissions**: `secrets:read`
4. Store the token securely:
- **Recommended**: AWS Systems Manager Parameter Store (SecureString)
- **Alternative**: AWS Secrets Manager
#### Using SSM Parameter Store
```bash
# Store token
aws ssm put-parameter \
--name /keyenv/token \
--value "your-service-token" \
--type SecureString
# Reference in serverless.yml
environment:
KEYENV_TOKEN: ${ssm:/keyenv/token}
```
### Security
- The service token should be stored in SSM Parameter Store or Secrets Manager
- Secrets are transmitted over HTTPS
- Secrets are cached in memory only (not written to disk)
- Lambda execution role needs no additional permissions
### Supported Runtimes
| Runtime | Supported |
|---------|-----------|
| Node.js 20.x | Yes |
| Node.js 18.x | Yes |
| Python 3.12 | Yes |
| Python 3.11 | Yes |
| Python 3.10 | Yes |
| Python 3.9 | Yes |
| Other runtimes | Use SDK instead |
### Self-Hosted KeyEnv
If you're running a self-hosted KeyEnv instance:
```yaml
environment:
KEYENV_API_URL: https://keyenv.your-company.com
```
### Troubleshooting
#### "Secrets not loading"
- Check CloudWatch logs for extension errors
- Verify `KEYENV_TOKEN` is set correctly
- Ensure the Lambda has internet access (VPC configuration)
#### "Authentication failed"
- Verify your token is correct
- Check the token hasn't expired
- Ensure the token is stored correctly in SSM/environment
#### "Access denied"
- The token may not have access to the specified project
- The token may not have access to the specified environment
- Check token permissions in KeyEnv dashboard
#### "Timeout during initialization"
- The KeyEnv API may be unreachable
- Check VPC and security group configuration
- Ensure NAT Gateway or VPC endpoints are configured
#### "High cold start latency"
- This is expected (~50-150ms overhead)
- Consider using Provisioned Concurrency for latency-sensitive functions
- The overhead only applies to cold starts
## Azure Functions
Load KeyEnv secrets in Azure Functions.
Source: https://keyenv.dev/docs/sdks/azure-functions/
Load secrets from KeyEnv in your Azure Functions.
### Prerequisites
- Azure account with a Function App
- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) installed
- KeyEnv service token with read access
### Quick Sync
Sync secrets to Function App settings:
```bash
export KEYENV_TOKEN=your-service-token
FUNCTION_APP="my-function-app"
RESOURCE_GROUP="my-resource-group"
# Export and sync
keyenv export -p YOUR_PROJECT_ID -e production --format json | \
jq -r '.secrets[] | "\(.key)=\(.value)"' | \
xargs -I {} az functionapp config appsettings set \
--name "$FUNCTION_APP" \
--resource-group "$RESOURCE_GROUP" \
--settings "{}"
```
### Sync Script
Create a reusable sync script:
```bash
#!/bin/bash
# sync-to-azure-functions.sh
set -euo pipefail
: "${KEYENV_TOKEN:?KEYENV_TOKEN is required}"
PROJECT_ID="${KEYENV_PROJECT:-YOUR_PROJECT_ID}"
ENVIRONMENT="${KEYENV_ENV:-production}"
FUNCTION_APP="${AZURE_FUNCTION_APP:-my-function-app}"
RESOURCE_GROUP="${AZURE_RESOURCE_GROUP:-my-resource-group}"
echo "Syncing KeyEnv ($ENVIRONMENT) to Azure Functions ($FUNCTION_APP)..."
# Export secrets and sync one by one
keyenv export -p "$PROJECT_ID" -e "$ENVIRONMENT" --format json | \
jq -r '.secrets[] | @base64' | while read -r secret; do
key=$(echo "$secret" | base64 -d | jq -r '.key')
value=$(echo "$secret" | base64 -d | jq -r '.value')
az functionapp config appsettings set \
--name "$FUNCTION_APP" \
--resource-group "$RESOURCE_GROUP" \
--settings "$key=$value" \
--output none
echo "Set: $key"
done
echo "Done!"
```
### Using SDK at Runtime
For dynamic secret loading, use the Node.js or Python SDK in your function.
#### Node.js Function
```typescript
// src/functions/httpTrigger.ts
import { app, HttpRequest, HttpResponseInit, InvocationContext } from "@azure/functions";
import { KeyEnv } from '@keyenv/node';
// Initialize once, outside the handler
const keyenv = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
cacheTtl: 300, // Cache for 5 minutes
});
let secretsLoaded = false;
export async function httpTrigger(request: HttpRequest, context: InvocationContext): Promise {
// Load secrets on first invocation
if (!secretsLoaded) {
await keyenv.loadEnv(process.env.KEYENV_PROJECT!, 'production');
secretsLoaded = true;
}
// Use secrets
const apiKey = process.env.API_KEY;
return {
body: JSON.stringify({ status: 'ok' }),
headers: { 'Content-Type': 'application/json' },
};
}
app.http('httpTrigger', {
methods: ['GET', 'POST'],
handler: httpTrigger,
});
```
#### Python Function
```python
# function_app.py
import azure.functions as func
import os
from keyenv import KeyEnv
app = func.FunctionApp()
# Initialize client
keyenv = KeyEnv(
token=os.environ["KEYENV_TOKEN"],
cache_ttl=300,
)
secrets_loaded = False
@app.route(route="hello")
def hello(req: func.HttpRequest) -> func.HttpResponse:
global secrets_loaded
if not secrets_loaded:
keyenv.load_env(os.environ["KEYENV_PROJECT"], "production")
secrets_loaded = True
api_key = os.environ.get("API_KEY")
return func.HttpResponse(f"Hello!")
```
### CI/CD Integration
#### GitHub Actions
```yaml
name: Deploy Azure Functions
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install KeyEnv CLI
run: curl -fsSL https://keyenv.dev/install.sh | bash
- name: Login to Azure
uses: azure/login@v1
with:
creds: ${{ secrets.AZURE_CREDENTIALS }}
- name: Sync secrets
run: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv export -p ${{ vars.KEYENV_PROJECT }} -e production --format json | \
jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
az functionapp config appsettings set \
--name ${{ vars.AZURE_FUNCTION_APP }} \
--resource-group ${{ vars.AZURE_RESOURCE_GROUP }} \
--settings "$key=$value" \
--output none
done
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
- name: Deploy Function App
uses: Azure/functions-action@v1
with:
app-name: ${{ vars.AZURE_FUNCTION_APP }}
package: .
```
#### Azure DevOps Pipeline
```yaml
trigger:
- main
pool:
vmImage: 'ubuntu-latest'
steps:
- script: curl -fsSL https://keyenv.dev/install.sh | bash
displayName: 'Install KeyEnv CLI'
- task: AzureCLI@2
displayName: 'Sync secrets'
inputs:
azureSubscription: 'your-subscription'
scriptType: 'bash'
scriptLocation: 'inlineScript'
inlineScript: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv export -p $(KEYENV_PROJECT) -e production --format json | \
jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
az functionapp config appsettings set \
--name $(AZURE_FUNCTION_APP) \
--resource-group $(AZURE_RESOURCE_GROUP) \
--settings "$key=$value" \
--output none
done
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
### Using Key Vault (Recommended)
For production, store secrets in Azure Key Vault:
#### 1. Sync to Key Vault
```bash
#!/bin/bash
VAULT_NAME="my-key-vault"
keyenv export -p YOUR_PROJECT_ID -e production --format json | \
jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
# Key Vault doesn't allow underscores, replace with dashes
vault_key=$(echo "$key" | tr '_' '-')
az keyvault secret set \
--vault-name "$VAULT_NAME" \
--name "$vault_key" \
--value "$value" \
--output none
echo "Set: $vault_key"
done
```
#### 2. Reference in Function App
```bash
# Add Key Vault reference
az functionapp config appsettings set \
--name my-function-app \
--resource-group my-resource-group \
--settings "DATABASE_URL=@Microsoft.KeyVault(VaultName=my-key-vault;SecretName=DATABASE-URL)"
```
### Deployment Slots
Sync different environments to different slots:
```bash
# Production slot
keyenv export -p YOUR_PROJECT_ID -e production --format json | \
jq -r '.secrets[]' | sync_to_slot "production"
# Staging slot
keyenv export -p YOUR_PROJECT_ID -e staging --format json | \
jq -r '.secrets[]' | sync_to_slot "staging"
# Helper function
sync_to_slot() {
local slot=$1
while IFS='=' read -r key value; do
if [ "$slot" == "production" ]; then
az functionapp config appsettings set \
--name "$FUNCTION_APP" \
--resource-group "$RESOURCE_GROUP" \
--settings "$key=$value"
else
az functionapp config appsettings set \
--name "$FUNCTION_APP" \
--resource-group "$RESOURCE_GROUP" \
--slot "$slot" \
--settings "$key=$value"
fi
done
}
```
### Best Practices
1. **Use Key Vault for production** - Better security and secret rotation
2. **Enable managed identity** - Let Functions access Key Vault without credentials
3. **Use deployment slots** - Test with staging secrets before production
4. **Cache secrets** - Use SDK caching to reduce API calls
### Troubleshooting
#### Settings Not Updating
Restart the Function App:
```bash
az functionapp restart \
--name my-function-app \
--resource-group my-resource-group
```
#### Key Vault Access Denied
Grant the Function App access:
```bash
az keyvault set-policy \
--name my-key-vault \
--object-id $(az functionapp identity show --name my-function-app --resource-group my-resource-group --query principalId -o tsv) \
--secret-permissions get list
```
#### Environment Variables Not Loading
Check current settings:
```bash
az functionapp config appsettings list \
--name my-function-app \
--resource-group my-resource-group
```
## Google Cloud Functions
Load KeyEnv secrets in Google Cloud Functions.
Source: https://keyenv.dev/docs/sdks/google-cloud-functions/
Load secrets from KeyEnv in your Google Cloud Functions.
### Prerequisites
- Google Cloud project with Cloud Functions enabled
- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed
- KeyEnv service token with read access
### Quick Sync
Deploy with secrets as environment variables:
```bash
export KEYENV_TOKEN=your-service-token
FUNCTION_NAME="my-function"
REGION="us-central1"
# Export to .env file
keyenv export -p YOUR_PROJECT_ID -e production --format dotenv > .env.production
# Deploy with env vars
gcloud functions deploy "$FUNCTION_NAME" \
--region="$REGION" \
--runtime=nodejs20 \
--trigger-http \
--env-vars-file=.env.production
```
### Sync Script
Create a reusable deployment script:
```bash
#!/bin/bash
# deploy-function.sh
set -euo pipefail
: "${KEYENV_TOKEN:?KEYENV_TOKEN is required}"
PROJECT_ID="${KEYENV_PROJECT:-YOUR_PROJECT_ID}"
ENVIRONMENT="${KEYENV_ENV:-production}"
FUNCTION_NAME="${FUNCTION_NAME:-my-function}"
REGION="${REGION:-us-central1}"
RUNTIME="${RUNTIME:-nodejs20}"
echo "Exporting secrets from KeyEnv ($ENVIRONMENT)..."
keyenv export -p "$PROJECT_ID" -e "$ENVIRONMENT" --format dotenv > .env.deploy
echo "Deploying $FUNCTION_NAME to Cloud Functions..."
gcloud functions deploy "$FUNCTION_NAME" \
--region="$REGION" \
--runtime="$RUNTIME" \
--trigger-http \
--allow-unauthenticated \
--env-vars-file=.env.deploy
# Cleanup
rm .env.deploy
echo "Done!"
```
### Using SDK at Runtime
For dynamic secret loading, use the Node.js or Python SDK.
#### Node.js Function
```javascript
// index.js
const { KeyEnv } = require('keyenv');
const functions = require('@google-cloud/functions-framework');
const keyenv = new KeyEnv({
token: process.env.KEYENV_TOKEN,
cacheTtl: 300, // Cache for 5 minutes
});
let secretsLoaded = false;
functions.http('helloWorld', async (req, res) => {
// Load secrets on first invocation (cached)
if (!secretsLoaded) {
await keyenv.loadEnv(process.env.KEYENV_PROJECT, 'production');
secretsLoaded = true;
}
// Use secrets
const apiKey = process.env.API_KEY;
res.send('Hello World!');
});
```
#### Python Function
```python
# main.py
import functions_framework
import os
from keyenv import KeyEnv
keyenv = KeyEnv(
token=os.environ["KEYENV_TOKEN"],
cache_ttl=300,
)
secrets_loaded = False
@functions_framework.http
def hello_world(request):
global secrets_loaded
if not secrets_loaded:
keyenv.load_env(os.environ["KEYENV_PROJECT"], "production")
secrets_loaded = True
api_key = os.environ.get("API_KEY")
return "Hello World!"
```
### Using Secret Manager (Recommended)
For production, store secrets in Google Secret Manager.
#### 1. Sync to Secret Manager
```bash
#!/bin/bash
# sync-to-secret-manager.sh
GCP_PROJECT="your-gcp-project"
keyenv export -p YOUR_PROJECT_ID -e production --format json | \
jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
if gcloud secrets describe "$key" --project="$GCP_PROJECT" &>/dev/null; then
echo -n "$value" | gcloud secrets versions add "$key" --data-file=- --project="$GCP_PROJECT"
echo "Updated: $key"
else
echo -n "$value" | gcloud secrets create "$key" --data-file=- --project="$GCP_PROJECT"
echo "Created: $key"
fi
done
```
#### 2. Access in Function
```javascript
// index.js
const { SecretManagerServiceClient } = require('@google-cloud/secret-manager');
const functions = require('@google-cloud/functions-framework');
const secretClient = new SecretManagerServiceClient();
const secrets = {};
async function loadSecret(name) {
if (!secrets[name]) {
const [version] = await secretClient.accessSecretVersion({
name: `projects/${process.env.GCP_PROJECT}/secrets/${name}/versions/latest`,
});
secrets[name] = version.payload.data.toString();
}
return secrets[name];
}
functions.http('helloWorld', async (req, res) => {
const apiKey = await loadSecret('API_KEY');
res.send('Hello!');
});
```
#### 3. Reference via Environment
Or reference secrets directly in deployment:
```bash
gcloud functions deploy my-function \
--region=us-central1 \
--runtime=nodejs20 \
--trigger-http \
--set-secrets="DATABASE_URL=DATABASE_URL:latest,API_KEY=API_KEY:latest"
```
### CI/CD Integration
#### GitHub Actions
```yaml
name: Deploy Cloud Function
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v4
- name: Install KeyEnv CLI
run: curl -fsSL https://keyenv.dev/install.sh | bash
- name: Authenticate to Google Cloud
uses: google-github-actions/auth@v2
with:
workload_identity_provider: ${{ vars.WIF_PROVIDER }}
service_account: ${{ vars.WIF_SERVICE_ACCOUNT }}
- name: Set up Cloud SDK
uses: google-github-actions/setup-gcloud@v2
- name: Sync secrets
run: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv export -p ${{ vars.KEYENV_PROJECT }} -e production --format json | \
jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
gcloud secrets versions add "$key" --data-file=- <<< "$value" 2>/dev/null || \
gcloud secrets create "$key" --data-file=- <<< "$value"
done
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
- name: Deploy function
run: |
gcloud functions deploy my-function \
--region=us-central1 \
--runtime=nodejs20 \
--trigger-http \
--set-secrets="DATABASE_URL=DATABASE_URL:latest,API_KEY=API_KEY:latest"
```
#### Cloud Build
```yaml
# cloudbuild.yaml
steps:
- name: 'gcr.io/cloud-builders/curl'
args: ['-fsSL', 'https://keyenv.dev/install.sh', '-o', 'install.sh']
- name: 'ubuntu'
entrypoint: 'bash'
args: ['install.sh']
- name: 'ubuntu'
entrypoint: 'bash'
args:
- '-c'
- |
export PATH="$$HOME/.keyenv/bin:$$PATH"
keyenv export -p $$KEYENV_PROJECT -e production --format dotenv > .env.deploy
secretEnv: ['KEYENV_TOKEN']
env:
- 'KEYENV_PROJECT=your-project-id'
- name: 'gcr.io/cloud-builders/gcloud'
args:
- 'functions'
- 'deploy'
- 'my-function'
- '--region=us-central1'
- '--runtime=nodejs20'
- '--trigger-http'
- '--env-vars-file=.env.deploy'
availableSecrets:
secretManager:
- versionName: projects/$PROJECT_ID/secrets/KEYENV_TOKEN/versions/latest
env: 'KEYENV_TOKEN'
```
### Gen 2 Functions
For Cloud Functions (2nd gen):
```bash
gcloud functions deploy my-function \
--gen2 \
--region=us-central1 \
--runtime=nodejs20 \
--trigger-http \
--entry-point=helloWorld \
--set-secrets="DATABASE_URL=DATABASE_URL:latest"
```
### Multiple Functions
Deploy multiple functions with shared secrets:
```bash
#!/bin/bash
FUNCTIONS=("api" "auth" "webhook")
REGION="us-central1"
# Export once
keyenv export -p YOUR_PROJECT_ID -e production --format dotenv > .env.deploy
for func in "${FUNCTIONS[@]}"; do
echo "Deploying $func..."
gcloud functions deploy "$func" \
--region="$REGION" \
--runtime=nodejs20 \
--trigger-http \
--env-vars-file=.env.deploy
done
rm .env.deploy
```
### Best Practices
1. **Use Secret Manager** - Better security and automatic rotation
2. **Cache secrets** - Use SDK caching for warm function reuse
3. **Grant minimal permissions** - Service accounts should only access needed secrets
4. **Use IAM bindings** - Control who can invoke functions
### Troubleshooting
#### Secret Access Denied
Grant the function's service account access:
```bash
gcloud secrets add-iam-policy-binding SECRET_NAME \
--member="serviceAccount:YOUR_PROJECT@appspot.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
```
#### Function Not Seeing New Secrets
Redeploy the function:
```bash
gcloud functions deploy my-function --region=us-central1 ...
```
#### Environment Variables Not Loading
Check current configuration:
```bash
gcloud functions describe my-function --region=us-central1
```
## Netlify
Inject KeyEnv secrets into your Netlify builds using the CLI.
Source: https://keyenv.dev/docs/sdks/netlify/
Inject KeyEnv secrets into your Netlify builds using the KeyEnv CLI.
### How It Works
The KeyEnv CLI pulls your secrets into a `.env` file before your build runs. Netlify automatically loads `.env` files during builds, making your secrets available as environment variables throughout the build process.
### Setup
#### 1. Add Your Service Token to Netlify
1. Go to your KeyEnv dashboard
2. Navigate to **Settings > Service Tokens**
3. Create a new token with:
- **Scope**: Select your project (recommended)
- **Permissions**: `secrets:read`
4. Add the token to Netlify:
- Go to **Site settings > Environment variables**
- Click **Add a variable**
- Key: `KEYENV_TOKEN`
- Value: Your service token
- Scopes: Select all (or specific contexts)
Also add `KEYENV_PROJECT` with your project ID if your token is not project-scoped.
#### 2. Install the CLI During Build
Update your build command in `netlify.toml` to install the KeyEnv CLI and pull secrets before building:
```toml
# netlify.toml
[build]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
publish = "dist"
```
That's it. The `keyenv pull` command writes a `.env` file that your build framework picks up automatically.
### Examples
#### React / Vite
```toml
# netlify.toml
[build]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
publish = "dist"
```
#### Next.js
```toml
# netlify.toml
[build]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
publish = ".next"
[[plugins]]
package = "@netlify/plugin-nextjs"
```
#### Gatsby
```toml
# netlify.toml
[build]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && gatsby build"
publish = "public"
```
#### Astro
```toml
# netlify.toml
[build]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
publish = "dist"
[[plugins]]
package = "@netlify/plugin-astro"
```
### Using a Build Script
For more control, create a build script:
```bash
#!/bin/bash
# scripts/netlify-build.sh
set -euo pipefail
# Install KeyEnv CLI
curl -fsSL https://keyenv.dev/install.sh | bash
# Pull secrets for the current environment
# Uses KEYENV_TOKEN and KEYENV_PROJECT from Netlify env vars
keyenv pull -e "${KEYENV_ENV:-production}" -o .env
echo "Loaded secrets from KeyEnv"
# Run the actual build
npm run build
```
Then reference it in `netlify.toml`:
```toml
[build]
command = "bash scripts/netlify-build.sh"
publish = "dist"
```
### Environment-Specific Builds
Use Netlify's deploy context environment variables to pull the right KeyEnv environment:
```toml
# netlify.toml
[build]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
publish = "dist"
# Override for deploy previews
[context.deploy-preview]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e staging -o .env && npm run build"
# Override for branch deploys
[context.branch-deploy]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e development -o .env && npm run build"
```
Or use a single command with a variable:
```toml
[build]
command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e $KEYENV_ENV -o .env && npm run build"
[context.production.environment]
KEYENV_ENV = "production"
[context.deploy-preview.environment]
KEYENV_ENV = "staging"
[context.branch-deploy.environment]
KEYENV_ENV = "development"
```
### Netlify Functions
Secrets pulled into `.env` are available to Netlify Functions at build time via `process.env`:
```javascript
// netlify/functions/api.js
export async function handler(event, context) {
const apiKey = process.env.API_KEY;
const response = await fetch('https://api.example.com', {
headers: { Authorization: `Bearer ${apiKey}` }
});
return {
statusCode: 200,
body: JSON.stringify(await response.json())
};
}
```
### Security
- The service token is stored securely in Netlify's environment variables
- Secrets are fetched over HTTPS
- The `.env` file is only present during the build and is not deployed
- Service tokens can be scoped to specific projects and environments
### Troubleshooting
#### "Authentication failed"
- Verify `KEYENV_TOKEN` is set in Netlify environment variables
- Check the token has not expired
- Ensure the token is available in the deploy context you are using
#### "Access denied"
- The token may not have access to the specified project
- The token may not have access to the target environment
- Check token permissions in the KeyEnv dashboard
#### "Project or environment not found"
- Verify the project ID is correct
- Check that the environment name matches exactly (case-sensitive)
- Ensure the environment exists in your KeyEnv project
#### Secrets not available during build
- Make sure `keyenv pull` runs **before** your build command
- Verify the `.env` file is being written to the project root
- Check the build logs for errors from the `keyenv pull` command
---
# API Reference
## API Reference
REST API reference generated from the KeyEnv OpenAPI specification.
Source: https://keyenv.dev/docs/api/
Complete reference for the KeyEnv REST API, generated from the OpenAPI 3.1.0 specification.
### Base URL
```
https://api.keyenv.dev
```
### OpenAPI specification
The machine-readable specification is published alongside these docs:
- [openapi.yaml](/openapi.yaml)
- [openapi.json](/openapi.json)
Import either file into Swagger Editor, Postman, Insomnia, or an AI agent to explore the API programmatically.
### Authentication
Every endpoint except `/health` and `/api/v1` requires a bearer token in the `Authorization` header. Both a Clerk JWT (web dashboard) and a KeyEnv service token (CI/CD, prefix `st_`) are accepted.
```bash
curl -H "Authorization: Bearer $KEYENV_TOKEN" \
https://api.keyenv.dev/api/v1/projects
```
### Endpoint groups
- [Health](/docs/api/health): Health check endpoints
- [Auth](/docs/api/auth): Authentication and user sync
- [Users](/docs/api/users): User management
- [Teams](/docs/api/teams): Team management and collaboration
- [Invitations](/docs/api/invitations): Team invitation management
- [Projects](/docs/api/projects): Project management
- [Environments](/docs/api/environments): Environment management within projects
- [Secrets](/docs/api/secrets): Secret management (encrypted key-value pairs)
- [Permissions](/docs/api/permissions): Environment-level access control
- [Tokens](/docs/api/tokens): Service token management for CI/CD
- [Rotations](/docs/api/rotations): Automated credential rotation for database secrets
- [Scans](/docs/api/scans): Secret scanning for detecting hardcoded secrets
- [ESO](/docs/api/eso): External Secrets Operator (ESO) webhook endpoints for Kubernetes integration.
- [Audit](/docs/api/audit): Audit log access
- [Billing](/docs/api/billing): Billing and usage information
- [CLI](/docs/api/cli): CLI authentication endpoints for device authorization flow
- [Account](/docs/api/account): GDPR and account management
## Health
Health check endpoints
Source: https://keyenv.dev/docs/api/health/
Health check endpoints
### Health check
```http
GET /health
```
Returns the health status of the API server
**Operation ID:** `healthCheck` · **Authentication:** none (public endpoint)
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Service is healthy | `HealthResponse` |
| `503` | Service is degraded | `HealthResponse` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `status` | `enum (ok, degraded)` | |
| `service` | `string` | |
| `version` | `string` | |
| `build_time` | `string` | |
| `checks` | `object` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/health"
```
### API info
```http
GET /api/v1
```
Returns basic API information
**Operation ID:** `apiInfo` · **Authentication:** none (public endpoint)
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | API information | `object` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | |
| `version` | `string` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1"
```
## Auth
Authentication and user sync
Source: https://keyenv.dev/docs/api/auth/
Authentication and user sync
### Sync user from Clerk
```http
POST /api/v1/auth/sync
```
Syncs user data from Clerk to KeyEnv. This should be called after a user signs up
or logs in to ensure their account exists in KeyEnv. Creates a personal team for
new users.
**Operation ID:** `authSync` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | User synced successfully | `User` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `clerk_id` | `string` | |
| `email` | `string (email)` | |
| `name` | `string` | |
| `avatar_url` | `string (uri)` | |
| `auth_type` | `enum (user, service_token)` | Authentication type. Only present for service token auth. |
| `team_id` | `string (uuid)` | Team ID. Only present for service token auth. |
| `project_ids` | `string (uuid)[]` | Project IDs the token has access to. Only present for service token auth. Tokens can access multiple projects. |
| `scopes` | `string[]` | Token scopes (e.g., read, write). Only present for service token auth. |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/auth/sync" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Users
User management
Source: https://keyenv.dev/docs/api/users/
User management
### Get current user
```http
GET /api/v1/users/me
```
Returns the currently authenticated user's profile
**Operation ID:** `getCurrentUser` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | User profile | `User` |
| `401` | Authentication required | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `clerk_id` | `string` | |
| `email` | `string (email)` | |
| `name` | `string` | |
| `avatar_url` | `string (uri)` | |
| `auth_type` | `enum (user, service_token)` | Authentication type. Only present for service token auth. |
| `team_id` | `string (uuid)` | Team ID. Only present for service token auth. |
| `project_ids` | `string (uuid)[]` | Project IDs the token has access to. Only present for service token auth. Tokens can access multiple projects. |
| `scopes` | `string[]` | Token scopes (e.g., read, write). Only present for service token auth. |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/users/me" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Teams
Team management and collaboration
Source: https://keyenv.dev/docs/api/teams/
Team management and collaboration
### List teams
```http
GET /api/v1/teams
```
Returns all teams the current user is a member of
**Operation ID:** `listTeams` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of teams | `object` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `teams` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/teams" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Create team
```http
POST /api/v1/teams
```
Creates a new team with the current user as owner
**Operation ID:** `createTeam` · **Authentication:** `Authorization: Bearer `
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Team created | `Team` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
#### Response body (`201`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `name` | `string` | |
| `slug` | `string` | |
| `plan` | `enum (free, team, enterprise)` | |
| `is_personal` | `boolean` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/teams" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"string"}'
```
### Get team
```http
GET /api/v1/teams/{teamId}
```
Returns team details including members
**Operation ID:** `getTeam` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Team details | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/teams/{teamId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Invite team member
```http
POST /api/v1/teams/{teamId}/members
```
Invites a user to join the team by email
**Operation ID:** `inviteTeamMember` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string (email)` | yes | |
| `role` | `enum (admin, developer, viewer)` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Member invited | `TeamMember` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`201`)
| Field | Type | Description |
| --- | --- | --- |
| `user_id` | `string (uuid)` | |
| `email` | `string (email)` | |
| `name` | `string` | |
| `avatar_url` | `string (uri)` | |
| `role` | `enum (owner, admin, developer, viewer)` | |
| `joined_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/teams/{teamId}/members" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email":"string","role":"admin"}'
```
### Update member role
```http
PATCH /api/v1/teams/{teamId}/members/{userId}
```
Updates a team member's role
**Operation ID:** `updateMemberRole` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
| `userId` | `string (uuid)` | yes | User UUID |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `enum (admin, developer, viewer)` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Role updated | `TeamMember` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `user_id` | `string (uuid)` | |
| `email` | `string (email)` | |
| `name` | `string` | |
| `avatar_url` | `string (uri)` | |
| `role` | `enum (owner, admin, developer, viewer)` | |
| `joined_at` | `string (date-time)` | |
#### Example
```bash
curl -X PATCH "https://api.keyenv.dev/api/v1/teams/{teamId}/members/{userId}" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"role":"admin"}'
```
### Remove team member
```http
DELETE /api/v1/teams/{teamId}/members/{userId}
```
Removes a member from the team
**Operation ID:** `removeTeamMember` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
| `userId` | `string (uuid)` | yes | User UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Member removed | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/teams/{teamId}/members/{userId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Invitations
Team invitation management
Source: https://keyenv.dev/docs/api/invitations/
Team invitation management
### List team invitations
```http
GET /api/v1/teams/{teamId}/invitations
```
Returns pending invitations for a team
**Operation ID:** `listTeamInvitations` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of invitations | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `team_id` | `string (uuid)` | |
| `email` | `string (email)` | |
| `role` | `enum (admin, member)` | |
| `invited_by` | `string (uuid)` | |
| `expires_at` | `string (date-time)` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/teams/{teamId}/invitations" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Revoke invitation
```http
DELETE /api/v1/teams/{teamId}/invitations/{invitationId}
```
Revokes a pending team invitation
**Operation ID:** `revokeInvitation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
| `invitationId` | `string (uuid)` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Invitation revoked | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/teams/{teamId}/invitations/{invitationId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Resend invitation
```http
POST /api/v1/teams/{teamId}/invitations/{invitationId}/resend
```
Resends a pending team invitation email
**Operation ID:** `resendInvitation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
| `invitationId` | `string (uuid)` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Invitation resent | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/teams/{teamId}/invitations/{invitationId}/resend" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### List my invitations
```http
GET /api/v1/invitations
```
Returns pending invitations for the current user
**Operation ID:** `listMyInvitations` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of invitations | `object[]` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `team_name` | `string` | |
| `invited_by_email` | `string (email)` | |
| `role` | `enum (admin, member)` | |
| `email` | `string (email)` | |
| `expires_at` | `string (date-time)` | |
| `token` | `string` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/invitations" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Get invitation by token
```http
GET /api/v1/invitations/{token}
```
Returns public information about an invitation
**Operation ID:** `getInvitationByToken` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Invitation details | `InvitationPublicInfo` |
| `401` | Authentication required | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `team_name` | `string` | |
| `invited_by_email` | `string (email)` | |
| `role` | `enum (admin, member)` | |
| `email` | `string (email)` | |
| `expires_at` | `string (date-time)` | |
| `token` | `string` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/invitations/{token}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Accept invitation
```http
POST /api/v1/invitations/{token}/accept
```
Accepts a team invitation and joins the team
**Operation ID:** `acceptInvitation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Invitation accepted | `Team` |
| `401` | Authentication required | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `name` | `string` | |
| `slug` | `string` | |
| `plan` | `enum (free, team, enterprise)` | |
| `is_personal` | `boolean` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/invitations/{token}/accept" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Projects
Project management
Source: https://keyenv.dev/docs/api/projects/
Project management
### List projects
```http
GET /api/v1/projects
```
Returns all projects the user has access to through their teams
**Operation ID:** `listProjects` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of projects | `object` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `projects` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Create project
```http
POST /api/v1/projects
```
Creates a new project within a team. Default environments (development, staging, production) are created automatically.
**Operation ID:** `createProject` · **Authentication:** `Authorization: Bearer `
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | `string (uuid)` | yes | |
| `name` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Project created | `Project` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `409` | A project whose name produces the same slug already exists in the team | `Error` |
| `429` | Plan limit exceeded | `LimitError` |
#### Response body (`201`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `team_id` | `string (uuid)` | |
| `name` | `string` | |
| `slug` | `string` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"team_id":"00000000-0000-0000-0000-000000000000","name":"string"}'
```
### Get project
```http
GET /api/v1/projects/{projectId}
```
Returns project details including environments
**Operation ID:** `getProject` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Project details | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Update project
```http
PATCH /api/v1/projects/{projectId}
```
Updates project name
**Operation ID:** `updateProject` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Project updated | `Project` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `team_id` | `string (uuid)` | |
| `name` | `string` | |
| `slug` | `string` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X PATCH "https://api.keyenv.dev/api/v1/projects/{projectId}" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"string"}'
```
### Delete project
```http
DELETE /api/v1/projects/{projectId}
```
Soft deletes a project and all its environments and secrets
**Operation ID:** `deleteProject` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Project deleted | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Environments
Environment management within projects
Source: https://keyenv.dev/docs/api/environments/
Environment management within projects
### List environments
```http
GET /api/v1/projects/{projectId}/environments
```
Returns all environments in a project
**Operation ID:** `listEnvironments` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of environments | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `environments` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Create environment
```http
POST /api/v1/projects/{projectId}/environments
```
Creates a new environment in a project. Can optionally inherit secrets from another environment.
Requires team admin role. The name is normalized to a slug (lowercase letters, numbers,
hyphens and underscores, e.g. "QA Env" becomes "qa-env") so it is safe in URLs and CLI commands.
**Operation ID:** `createEnvironment` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | Environment name, normalized to a slug (lowercase letters, numbers, hyphens and underscores) |
| `inherits_from` | `string (uuid)` | no | Parent environment ID for secret inheritance |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Environment created | `Environment` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `409` | Resource already exists | `Error` |
| `429` | Plan limit exceeded | `LimitError` |
#### Response body (`201`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `project_id` | `string (uuid)` | |
| `name` | `string` | |
| `inherits_from` | `string (uuid)` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"string","inherits_from":"00000000-0000-0000-0000-000000000000"}'
```
### Get environment
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}
```
Returns environment details
**Operation ID:** `getEnvironment` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Environment details | `Environment` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `project_id` | `string (uuid)` | |
| `name` | `string` | |
| `inherits_from` | `string (uuid)` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Rename environment
```http
PATCH /api/v1/projects/{projectId}/environments/{environmentId}
```
Renames a custom environment. Requires team admin role. The new name is normalized to a slug.
Default environments (development, staging, production) cannot be renamed.
Secrets, permissions and inheritance are kept because they reference the environment ID.
Logs an `environment.updated` audit event.
**Operation ID:** `updateEnvironment` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | New name, normalized to a slug (lowercase letters, numbers, hyphens and underscores) |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Environment renamed | `Environment` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
| `409` | Resource already exists | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `project_id` | `string (uuid)` | |
| `name` | `string` | |
| `inherits_from` | `string (uuid)` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X PATCH "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"string"}'
```
### Delete environment
```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}
```
Deletes an environment with its secrets, permissions, overrides and rotation configs. Requires team admin role.
Cannot delete default environments (development, staging, production).
Returns 409 if other environments inherit from it; change or delete those first.
**Operation ID:** `deleteEnvironment` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Environment deleted | |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
| `409` | Resource already exists | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Secrets
Secret management (encrypted key-value pairs)
Source: https://keyenv.dev/docs/api/secrets/
Secret management (encrypted key-value pairs)
### List secrets
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets
```
Returns all secrets in an environment (keys and metadata only, no values). Includes inherited secrets from parent environments.
**Operation ID:** `listSecrets` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of secrets | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `secrets` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Create secret
```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/secrets
```
Creates a new secret in an environment
**Operation ID:** `createSecret` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | yes | Must be uppercase letters, numbers, and underscores, starting with a letter |
| `value` | `string` | yes | |
| `description` | `string` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Secret created | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `409` | Resource already exists | `Error` |
| `429` | Plan limit exceeded | `LimitError` |
#### Response body (`201`)
| Field | Type | Description |
| --- | --- | --- |
| `secret` | `Secret` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"DATABASE_URL","value":"string","description":"string"}'
```
### Export secrets
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets/export
```
Exports all secrets with their decrypted values. Use this for CI/CD or local development.
Includes inherited secrets from parent environments.
**Note:** This endpoint logs an audit event for compliance.
**Operation ID:** `exportSecrets` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Secrets with values | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `secrets` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/export" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### List secret value hashes
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets/hashes
```
Returns every secret (including inherited ones) with a keyed hash of its value instead of the plaintext,
for comparing environments. Hashes are HMAC-SHA256 with a server-side key derived from the encryption key
and scoped to the project, so equal values in the same project hash equal but cannot be brute-forced offline.
Requires read access to the environment. Plaintext is not returned, so no `secret.read` audit event is logged.
**Operation ID:** `listSecretHashes` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret value hashes | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `data` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/hashes" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Bulk import secrets
```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/secrets/bulk
```
Imports multiple secrets at once. Useful for migrating from .env files or other systems.
- Maximum 100 secrets per request
- Set `overwrite: true` to update existing secrets
- Set `overwrite: false` to skip existing secrets
**Operation ID:** `bulkImportSecrets` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `secrets` | `object[]` | yes | |
| `overwrite` | `boolean` | no | Whether to overwrite existing secrets |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Import results | `BulkImportResult` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `429` | Plan limit exceeded | `LimitError` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `created` | `integer` | Number of secrets created |
| `updated` | `integer` | Number of secrets updated (when overwrite=true) |
| `skipped` | `integer` | Number of secrets skipped (existing, when overwrite=false) |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/bulk" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"secrets":[{"key":"string","value":"string","description":"string"}],"overwrite":false}'
```
### Get secret
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}
```
Returns a single secret with its decrypted value
**Operation ID:** `getSecret` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `key` | `string` | yes | Secret key (uppercase letters, numbers, underscores) |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret with value | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `secret` | `object` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Update secret
```http
PUT /api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}
```
Updates a secret's value and/or description. Previous values are preserved in history.
**Operation ID:** `updateSecret` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `key` | `string` | yes | Secret key (uppercase letters, numbers, underscores) |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | yes | |
| `description` | `string` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret updated | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `secret` | `Secret` | |
#### Example
```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"value":"string","description":"string"}'
```
### Delete secret
```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}
```
Permanently deletes a secret
**Operation ID:** `deleteSecret` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `key` | `string` | yes | Secret key (uppercase letters, numbers, underscores) |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Secret deleted | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Get secret history
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}/history
```
Returns the version history of a secret with decrypted values
**Operation ID:** `getSecretHistory` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `key` | `string` | yes | Secret key (uppercase letters, numbers, underscores) |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret history | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `history` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}/history" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Permissions
Environment-level access control
Source: https://keyenv.dev/docs/api/permissions/
Environment-level access control
### Get my permissions
```http
GET /api/v1/projects/{projectId}/my-permissions
```
Returns the current user's permissions for all environments in a project
**Operation ID:** `getMyPermissions` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | User permissions | `MyPermissionsResponse` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `permissions` | `object[]` | |
| `is_team_admin` | `boolean` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/my-permissions" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### List environment permissions
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/permissions
```
Lists all user permissions for an environment
**Operation ID:** `listEnvironmentPermissions` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of permissions | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `environment_id` | `string (uuid)` | |
| `user_id` | `string (uuid)` | |
| `user_email` | `string (email)` | |
| `role` | `enum (none, read, write, admin)` | |
| `granted_by` | `string (uuid)` | |
| `created_at` | `string (date-time)` | |
| `updated_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Bulk set permissions
```http
PUT /api/v1/projects/{projectId}/environments/{environmentId}/permissions
```
Sets permissions for multiple users at once
**Operation ID:** `bulkSetPermissions` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `permissions` | `object[]` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Permissions updated | |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Example
```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"permissions":[{"user_id":"00000000-0000-0000-0000-000000000000","role":"none"}]}'
```
### Get user permission
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}
```
Returns a specific user's permission for an environment
**Operation ID:** `getUserPermission` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `userId` | `string (uuid)` | yes | User UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | User permission | `EnvironmentPermission` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `environment_id` | `string (uuid)` | |
| `user_id` | `string (uuid)` | |
| `user_email` | `string (email)` | |
| `role` | `enum (none, read, write, admin)` | |
| `granted_by` | `string (uuid)` | |
| `created_at` | `string (date-time)` | |
| `updated_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Set user permission
```http
PUT /api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}
```
Sets a user's permission for an environment
**Operation ID:** `setUserPermission` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `userId` | `string (uuid)` | yes | User UUID |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `enum (none, read, write, admin)` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Permission set | `EnvironmentPermission` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `environment_id` | `string (uuid)` | |
| `user_id` | `string (uuid)` | |
| `user_email` | `string (email)` | |
| `role` | `enum (none, read, write, admin)` | |
| `granted_by` | `string (uuid)` | |
| `created_at` | `string (date-time)` | |
| `updated_at` | `string (date-time)` | |
#### Example
```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"role":"none"}'
```
### Delete user permission
```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}
```
Removes a user's explicit permission for an environment
**Operation ID:** `deleteUserPermission` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `userId` | `string (uuid)` | yes | User UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Permission deleted | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Get default permissions
```http
GET /api/v1/projects/{projectId}/permissions/defaults
```
Returns default permissions for new team members in a project
**Operation ID:** `getDefaultPermissions` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Default permissions | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `project_id` | `string (uuid)` | |
| `environment_name` | `string` | Environment name or "*" for all |
| `default_role` | `enum (none, read, write, admin)` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/permissions/defaults" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Set default permissions
```http
PUT /api/v1/projects/{projectId}/permissions/defaults
```
Sets default permissions for new team members
**Operation ID:** `setDefaultPermissions` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaults` | `object[]` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Defaults updated | |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Example
```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/permissions/defaults" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"defaults":[{"environment_name":"string","default_role":"none"}]}'
```
## Tokens
Service token management for CI/CD
Source: https://keyenv.dev/docs/api/tokens/
Service token management for CI/CD
### List service tokens
```http
GET /api/v1/tokens
```
Returns all service tokens created by the user
**Operation ID:** `listTokens` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of tokens | `object` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `tokens` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/tokens" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Create service token
```http
POST /api/v1/tokens
```
Creates a new service token for CI/CD or programmatic access.
**Important:** The token value is only returned once upon creation. Store it securely.
**Operation ID:** `createToken` · **Authentication:** `Authorization: Bearer `
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | |
| `team_id` | `string (uuid)` | yes | |
| `scopes` | `enum (read, write)[]` | yes | |
| `expires_at` | `string (date-time)` | no | Optional expiration date |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Token created | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/tokens" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"string","team_id":"00000000-0000-0000-0000-000000000000","scopes":["read"],"expires_at":"string"}'
```
### Delete service token
```http
DELETE /api/v1/tokens/{tokenId}
```
Permanently revokes a service token
**Operation ID:** `deleteToken` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tokenId` | `string (uuid)` | yes | Service token UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Token deleted | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/tokens/{tokenId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Rotate service token
```http
POST /api/v1/tokens/{tokenId}/rotate
```
Rotates a service token, creating a new one with an optional grace period
during which the old token remains valid. This allows seamless token rotation
in CI/CD systems.
**Operation ID:** `rotateToken` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tokenId` | `string (uuid)` | yes | Service token UUID |
#### Request body
`application/json`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grace_period_minutes` | `integer` | no | How long the old token remains valid |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Token rotated successfully | `RotateTokenResponse` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `new_token` | `object` | |
| `old_token_expires_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/tokens/{tokenId}/rotate" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"grace_period_minutes":5}'
```
## Rotations
Automated credential rotation for database secrets
Source: https://keyenv.dev/docs/api/rotations/
Automated credential rotation for database secrets
### List rotations
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/rotations
```
Lists all rotation configurations for an environment
**Operation ID:** `listRotations` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of rotations | `RotationConfigListResponse` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `rotations` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Create rotation
```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/rotations
```
Creates a new automated credential rotation configuration
**Operation ID:** `createRotation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | |
| `integration_type` | `enum (postgresql, mysql)` | yes | |
| `connection_method` | `enum (direct, proxied)` | yes | |
| `connection` | `object` | yes | |
| `proxy` | `object` | no | |
| `rotation_interval_days` | `integer` | yes | |
| `permission_level` | `string` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Rotation created | `RotationConfigResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`201`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `environment_id` | `string (uuid)` | |
| `name` | `string` | |
| `integration_type` | `enum (postgresql, mysql)` | |
| `rotation_interval_days` | `integer` | |
| `connection_method` | `enum (direct, proxied)` | |
| `status` | `enum (active, paused, disabled, error)` | |
| `last_rotation_at` | `string (date-time)` | |
| `next_rotation_at` | `string (date-time)` | |
| `error_message` | `string` | |
| `injected_secrets` | `string[]` | |
| `created_at` | `string (date-time)` | |
| `updated_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"string","integration_type":"postgresql","connection_method":"direct","connection":{"host":"string","port":0,"database":"string","admin_username":"string","admin_password":"string","ssl_mode":"string"},"proxy":{"lambda_arn":"string","region":"string","shared_secret":"string"},"rotation_interval_days":0,"permission_level":"string"}'
```
### Test connection
```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/rotations/test
```
Tests database connection without saving the rotation config
**Operation ID:** `testRotationConnection` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `integration_type` | `enum (postgresql, mysql)` | yes | |
| `connection_method` | `enum (direct, proxied)` | yes | |
| `connection` | `object` | yes | |
| `proxy` | `object` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Connection test result | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `success` | `boolean` | |
| `message` | `string` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/test" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"integration_type":"postgresql","connection_method":"direct","connection":{"host":"string","port":0,"database":"string","admin_username":"string","admin_password":"string","ssl_mode":"string"},"proxy":{"lambda_arn":"string","region":"string","shared_secret":"string"}}'
```
### Get rotation
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}
```
Returns a rotation configuration by name
**Operation ID:** `getRotation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Rotation details | `RotationConfigResponse` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `environment_id` | `string (uuid)` | |
| `name` | `string` | |
| `integration_type` | `enum (postgresql, mysql)` | |
| `rotation_interval_days` | `integer` | |
| `connection_method` | `enum (direct, proxied)` | |
| `status` | `enum (active, paused, disabled, error)` | |
| `last_rotation_at` | `string (date-time)` | |
| `next_rotation_at` | `string (date-time)` | |
| `error_message` | `string` | |
| `injected_secrets` | `string[]` | |
| `created_at` | `string (date-time)` | |
| `updated_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Update rotation
```http
PUT /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}
```
Updates rotation interval or status
**Operation ID:** `updateRotation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rotation_interval_days` | `integer` | no | |
| `status` | `enum (active, paused)` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Rotation updated | `RotationConfigResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `environment_id` | `string (uuid)` | |
| `name` | `string` | |
| `integration_type` | `enum (postgresql, mysql)` | |
| `rotation_interval_days` | `integer` | |
| `connection_method` | `enum (direct, proxied)` | |
| `status` | `enum (active, paused, disabled, error)` | |
| `last_rotation_at` | `string (date-time)` | |
| `next_rotation_at` | `string (date-time)` | |
| `error_message` | `string` | |
| `injected_secrets` | `string[]` | |
| `created_at` | `string (date-time)` | |
| `updated_at` | `string (date-time)` | |
#### Example
```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"rotation_interval_days":0,"status":"active"}'
```
### Delete rotation
```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}
```
Deletes a rotation configuration
**Operation ID:** `deleteRotation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Rotation deleted | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Trigger rotation
```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/rotate
```
Manually triggers a credential rotation
**Operation ID:** `triggerRotation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Rotation triggered | `RotationHistory` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `rotation_config_id` | `string (uuid)` | |
| `version` | `integer` | |
| `triggered_by` | `string (uuid)` | |
| `trigger_type` | `enum (scheduled, manual)` | |
| `status` | `enum (success, failed, rolled_back)` | |
| `started_at` | `string (date-time)` | |
| `completed_at` | `string (date-time)` | |
| `error_message` | `string` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/rotate" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Test existing rotation
```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/test
```
Tests database connection for an existing rotation
**Operation ID:** `testExistingRotation` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Test result | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `success` | `boolean` | |
| `message` | `string` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/test" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Get rotation history
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/history
```
Returns rotation execution history
**Operation ID:** `getRotationHistory` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Rotation history | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `rotation_config_id` | `string (uuid)` | |
| `version` | `integer` | |
| `triggered_by` | `string (uuid)` | |
| `trigger_type` | `enum (scheduled, manual)` | |
| `status` | `enum (success, failed, rolled_back)` | |
| `started_at` | `string (date-time)` | |
| `completed_at` | `string (date-time)` | |
| `error_message` | `string` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/history" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### List rotation webhooks
```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks
```
Lists webhooks for a rotation configuration
**Operation ID:** `listRotationWebhooks` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of webhooks | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `rotation_config_id` | `string (uuid)` | |
| `url` | `string (uri)` | |
| `events` | `enum (rotation.started, rotation.completed, rotation.failed)[]` | |
| `enabled` | `boolean` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Create rotation webhook
```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks
```
Creates a webhook for rotation events
**Operation ID:** `createRotationWebhook` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string (uri)` | yes | |
| `events` | `enum (rotation.started, rotation.completed, rotation.failed)[]` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Webhook created | `RotationWebhook` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`201`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `rotation_config_id` | `string (uuid)` | |
| `url` | `string (uri)` | |
| `events` | `enum (rotation.started, rotation.completed, rotation.failed)[]` | |
| `enabled` | `boolean` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"string","events":["rotation.started"]}'
```
### Delete rotation webhook
```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks/{webhookId}
```
Deletes a rotation webhook
**Operation ID:** `deleteRotationWebhook` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `rotationName` | `string` | yes | Rotation configuration name |
| `webhookId` | `string (uuid)` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `204` | Webhook deleted | |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks/{webhookId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Scans
Secret scanning for detecting hardcoded secrets
Source: https://keyenv.dev/docs/api/scans/
Secret scanning for detecting hardcoded secrets
### List scans
```http
GET /api/v1/projects/{projectId}/scans
```
Lists secret scan results for a project
**Operation ID:** `listScans` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | List of scans | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `project_id` | `string (uuid)` | |
| `source` | `enum (cli, action, app)` | |
| `commit_sha` | `string` | |
| `branch` | `string` | |
| `findings_count` | `integer` | |
| `created_at` | `string (date-time)` | |
| `created_by` | `string (uuid)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/scans" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Upload scan results
```http
POST /api/v1/projects/{projectId}/scans
```
Uploads secret scan results from CLI or GitHub Action
**Operation ID:** `uploadScan` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `findings` | `object[]` | no | |
| `source` | `enum (cli, action, app)` | no | |
| `commit_sha` | `string` | no | |
| `branch` | `string` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `201` | Scan uploaded | `UploadScanResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`201`)
| Field | Type | Description |
| --- | --- | --- |
| `scan_id` | `string (uuid)` | |
| `findings_count` | `integer` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/scans" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"findings":[{"pattern_id":"string","pattern_name":"string","severity":"critical","file_path":"string","line_number":0,"matched_text":"string"}],"source":"cli","commit_sha":"string","branch":"string"}'
```
### Get scan
```http
GET /api/v1/projects/{projectId}/scans/{scanId}
```
Returns a scan with its findings
**Operation ID:** `getScan` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `scanId` | `string (uuid)` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Scan details with findings | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/scans/{scanId}" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Update finding status
```http
PATCH /api/v1/projects/{projectId}/scans/{scanId}/findings/{findingId}
```
Updates a scan finding status (dismiss or reactivate)
**Operation ID:** `updateFindingStatus` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `scanId` | `string (uuid)` | yes | |
| `findingId` | `string (uuid)` | yes | |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `enum (active, dismissed, fixed)` | yes | |
| `dismissed_reason` | `string` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Finding updated | `ScanFinding` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | |
| `scan_id` | `string (uuid)` | |
| `pattern_id` | `string` | |
| `pattern_name` | `string` | |
| `severity` | `enum (critical, high, medium, low)` | |
| `file_path` | `string` | |
| `line_number` | `integer` | |
| `snippet` | `string` | |
| `status` | `enum (active, dismissed, fixed)` | |
| `dismissed_by` | `string (uuid)` | |
| `dismissed_at` | `string (date-time)` | |
| `dismissed_reason` | `string` | |
| `created_at` | `string (date-time)` | |
#### Example
```bash
curl -X PATCH "https://api.keyenv.dev/api/v1/projects/{projectId}/scans/{scanId}/findings/{findingId}" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"active","dismissed_reason":"string"}'
```
## ESO
External Secrets Operator (ESO) webhook endpoints for Kubernetes integration.
Source: https://keyenv.dev/docs/api/eso/
External Secrets Operator (ESO) webhook endpoints for Kubernetes integration.
These endpoints allow ESO to fetch secrets from KeyEnv and sync them to Kubernetes Secrets.
**Authentication:** Service token required (user authentication not supported).
See the [Kubernetes ESO Integration Guide](https://docs.keyenv.dev/integrations/kubernetes-eso) for setup instructions.
### Get single secret for ESO
```http
GET /api/v1/eso/secret
```
Fetches a single secret value for External Secrets Operator webhook integration.
This endpoint is designed for ESO's webhook provider to fetch individual secrets.
The environment can be specified by name or ID.
**Authentication:** Only service token authentication is supported. User authentication
will return 403 Forbidden.
**Environment Inheritance:** If the secret is not found in the specified environment,
the inheritance chain is searched (child environments inherit from parents).
**Operation ID:** `getESOSecret` · **Authentication:** `Authorization: Bearer `
#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | `string` | yes | Project ID or slug |
| `env` | `string` | yes | Environment name or ID |
| `key` | `string` | yes | Secret key name |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret value retrieved successfully | `ESOSecretResponse` |
| `400` | Bad request. Possible causes: - Missing required query parameters (project, env, key) - Circular environment inheritance detected | `Error` |
| `401` | Authentication required or invalid token | `Error` |
| `403` | Forbidden. Possible causes: - Service token does not have access to this project - User authentication was used (ESO requires service token) | `Error` |
| `404` | Not found. Possible causes: - Project not found - Environment not found - Secret not found (including in inherited environments) | `Error` |
| `500` | Internal server error (e.g., decryption failure) | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `value` | `string` | The decrypted secret value |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/eso/secret" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Get all secrets for ESO dataFrom
```http
GET /api/v1/eso/secrets
```
Fetches all secrets as a key-value map for External Secrets Operator's `dataFrom` feature.
This endpoint is designed for ESO's webhook provider to bulk-fetch all secrets from
an environment. The environment can be specified by name or ID.
**Authentication:** Only service token authentication is supported. User authentication
will return 403 Forbidden.
**Environment Inheritance:** Secrets are resolved through the inheritance chain.
Child environment values override parent values for the same key.
**Hidden Secrets:** Secrets that have been explicitly hidden (overridden with no value)
in the target environment are excluded from the response.
**Operation ID:** `getESOSecrets` · **Authentication:** `Authorization: Bearer `
#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | `string` | yes | Project ID or slug |
| `env` | `string` | yes | Environment name or ID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | All secrets retrieved successfully | `ESOSecretsResponse` |
| `400` | Bad request. Possible causes: - Missing required query parameters (project, env) - Circular environment inheritance detected | `Error` |
| `401` | Authentication required or invalid token | `Error` |
| `403` | Forbidden. Possible causes: - Service token does not have access to this project - User authentication was used (ESO requires service token) | `Error` |
| `404` | Not found. Possible causes: - Project not found - Environment not found | `Error` |
| `500` | Internal server error (e.g., decryption failure) | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `secrets` | `object` | Key-value map of all secrets in the environment |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/eso/secrets" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Audit
Audit log access
Source: https://keyenv.dev/docs/api/audit/
Audit log access
### List audit logs
```http
GET /api/v1/audit
```
Returns audit logs for teams the user has access to
**Operation ID:** `listAuditLogs` · **Authentication:** `Authorization: Bearer `
#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | `string (uuid)` | no | Filter by team ID |
| `limit` | `integer` | no | Maximum number of results |
| `offset` | `integer` | no | Number of results to skip |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Audit logs | `object` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `logs` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/audit" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### List team audit logs
```http
GET /api/v1/teams/{teamId}/audit
```
Returns audit logs for a specific team
**Operation ID:** `listTeamAuditLogs` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | Maximum number of results |
| `offset` | `integer` | no | Number of results to skip |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Audit logs | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `logs` | `object[]` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/teams/{teamId}/audit" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Billing
Billing and usage information
Source: https://keyenv.dev/docs/api/billing/
Billing and usage information
### Get team usage
```http
GET /api/v1/teams/{teamId}/usage
```
Returns current usage statistics for a team
**Operation ID:** `getTeamUsage` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Usage statistics | `UsageStats` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `projects` | `integer` | |
| `environments` | `integer` | |
| `secrets` | `integer` | |
| `members` | `integer` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/teams/{teamId}/usage" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Get team limits
```http
GET /api/v1/teams/{teamId}/limits
```
Returns plan limits for a team
**Operation ID:** `getTeamLimits` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Plan limits | `PlanLimits` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `plan` | `enum (free, team, enterprise)` | |
| `projects` | `integer` | Maximum number of projects (-1 for unlimited) |
| `environments_per_project` | `integer` | |
| `secrets_per_environment` | `integer` | |
| `members` | `integer` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/teams/{teamId}/limits" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Get billing info
```http
GET /api/v1/teams/{teamId}/billing
```
Returns billing information including current plan and subscription status
**Operation ID:** `getTeamBilling` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Billing information | `BillingInfo` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `plan` | `enum (free, team, enterprise)` | |
| `status` | `enum (active, canceled, past_due, trialing)` | |
| `current_period_end` | `string (date-time)` | |
| `cancel_at_period_end` | `boolean` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/teams/{teamId}/billing" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Create checkout session
```http
POST /api/v1/teams/{teamId}/checkout
```
Creates a Stripe checkout session for upgrading the team's plan
**Operation ID:** `createCheckoutSession` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plan` | `enum (team, enterprise)` | yes | |
| `success_url` | `string (uri)` | no | |
| `cancel_url` | `string (uri)` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Checkout session created | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string (uri)` | URL to redirect the user to for checkout |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/teams/{teamId}/checkout" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"plan":"team","success_url":"string","cancel_url":"string"}'
```
### Create billing portal session
```http
POST /api/v1/teams/{teamId}/portal
```
Creates a Stripe billing portal session for managing subscription
**Operation ID:** `createPortalSession` · **Authentication:** `Authorization: Bearer `
#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | `string (uuid)` | yes | Team UUID |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Portal session created | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string (uri)` | URL to redirect the user to for the billing portal |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/teams/{teamId}/portal" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## CLI
CLI authentication endpoints for device authorization flow
Source: https://keyenv.dev/docs/api/cli/
CLI authentication endpoints for device authorization flow
### Initiate CLI login
```http
POST /api/v1/cli/login
```
Initiates the CLI login flow, returns a URL to open in the browser
**Operation ID:** `cliLogin` · **Authentication:** none (public endpoint)
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `redirect_uri` | `string (uri)` | yes | |
| `device_name` | `string` | no | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Login URL generated | `CLILoginResponse` |
| `400` | Invalid request | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `auth_url` | `string (uri)` | |
| `state` | `string` | |
| `expires_in` | `integer` | Seconds until state expires |
| `user_code` | `string` | Verification code derived from the state (first 8 uppercase hex chars of SHA-256(state), formatted XXXX-XXXX). The CLI displays it and the browser consent screen shows the same code so the user can confirm they match. |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/cli/login" \
-H "Content-Type: application/json" \
-d '{"redirect_uri":"string","device_name":"string"}'
```
### Complete CLI login
```http
POST /api/v1/cli/callback
```
Called by the web app after browser authentication completes
**Operation ID:** `cliCallback` · **Authentication:** `Authorization: Bearer `
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Login completed | `CLICallbackResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `access_token` | `string` | |
| `refresh_token` | `string` | |
| `expires_at` | `string (date-time)` | |
| `user` | `object` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/cli/callback" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"state":"string"}'
```
### Poll CLI login status
```http
GET /api/v1/cli/status
```
Polls the status of a CLI login flow
**Operation ID:** `cliStatus` · **Authentication:** none (public endpoint)
#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Login status | `CLIStatusResponse` |
| `400` | Invalid request | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `status` | `enum (pending, completed, expired)` | |
| `refresh_token` | `string` | |
| `user` | `object` | |
| `expires_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/cli/status"
```
### Refresh CLI token
```http
POST /api/v1/cli/refresh
```
Refreshes an expired access token using a refresh token
**Operation ID:** `cliRefresh` · **Authentication:** none (public endpoint)
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refresh_token` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | New access token | `CLIRefreshResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `access_token` | `string` | |
| `expires_at` | `string (date-time)` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/cli/refresh" \
-H "Content-Type: application/json" \
-d '{"refresh_token":"string"}'
```
### CLI logout
```http
POST /api/v1/cli/logout
```
Revokes the CLI session
**Operation ID:** `cliLogout` · **Authentication:** none (public endpoint)
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refresh_token` | `string` | yes | |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Logged out | |
| `400` | Invalid request | `Error` |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/cli/logout" \
-H "Content-Type: application/json" \
-d '{"refresh_token":"string"}'
```
### CLI whoami
```http
GET /api/v1/cli/whoami
```
Returns the current user and session info
**Operation ID:** `cliWhoami` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | User and session info | `CLIWhoamiResponse` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `user` | `object` | |
| `teams` | `object[]` | |
| `session_created_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/cli/whoami" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
## Account
GDPR and account management
Source: https://keyenv.dev/docs/api/account/
GDPR and account management
### Get data export status
```http
GET /api/v1/account/data-export
```
Returns the status of a pending data export request
**Operation ID:** `getDataExportStatus` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Export status | `DataExportStatusResponse` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `status` | `enum (none, pending, ready, expired)` | |
| `requested_at` | `string (date-time)` | |
| `expires_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/account/data-export" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Request data export
```http
POST /api/v1/account/data-export/request
```
Requests a GDPR data export
**Operation ID:** `requestDataExport` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Export requested | `DataExportRequestResponse` |
| `401` | Authentication required | `Error` |
| `409` | Resource already exists | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | |
| `message` | `string` | |
#### Example
```bash
curl -X POST "https://api.keyenv.dev/api/v1/account/data-export/request" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Download data export
```http
GET /api/v1/account/data-export/download
```
Downloads the completed data export
**Operation ID:** `downloadDataExport` · **Authentication:** `Authorization: Bearer `
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Export data | `UserDataExport` |
| `401` | Authentication required | `Error` |
| `404` | Resource not found | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `user` | `object` | |
| `teams` | `object[]` | |
| `exported_at` | `string (date-time)` | |
#### Example
```bash
curl -X GET "https://api.keyenv.dev/api/v1/account/data-export/download" \
-H "Authorization: Bearer $KEYENV_TOKEN"
```
### Delete account
```http
DELETE /api/v1/account
```
Permanently deletes the user account and all associated data
**Operation ID:** `deleteAccount` · **Authentication:** `Authorization: Bearer `
#### Request body
`application/json` (required)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirmation` | `string` | yes | Must be "DELETE" |
#### Responses
| Status | Description | Body |
| --- | --- | --- |
| `200` | Account deleted | `DeleteAccountResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
#### Response body (`200`)
| Field | Type | Description |
| --- | --- | --- |
| `success` | `boolean` | |
| `message` | `string` | |
#### Example
```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/account" \
-H "Authorization: Bearer $KEYENV_TOKEN" \
-H "Content-Type: application/json" \
-d '{"confirmation":"string"}'
```
---
# Guides
## Guides
Step-by-step guides for common workflows.
Source: https://keyenv.dev/docs/guides/
Practical guides for integrating KeyEnv into your workflow.
### CI/CD Platforms
- [CI/CD Integration](/docs/guides/ci-cd) - Set up automated secret management
- [GitLab CI/CD](/docs/guides/gitlab-ci) - Integrate KeyEnv with GitLab pipelines
- [CircleCI](/docs/guides/circleci) - Use the KeyEnv orb in CircleCI workflows
- [Azure Pipelines](/docs/guides/azure-pipelines) - Use KeyEnv with Azure DevOps
- [Jenkins](/docs/guides/jenkins) - Integrate KeyEnv with Jenkins pipelines
- [Travis CI](/docs/guides/travis-ci) - Use KeyEnv with Travis CI
### Hosting Platforms
- [Vercel](/docs/guides/vercel) - Sync secrets to Vercel projects automatically
- [Railway](/docs/guides/railway) - Sync secrets to Railway projects
- [Render](/docs/guides/render) - Use KeyEnv with Render deployments
- [Fly.io](/docs/guides/flyio) - Deploy to Fly.io with KeyEnv secrets
- [Cloudflare Workers](/docs/guides/cloudflare-workers) - Use KeyEnv with Cloudflare Workers
- [Google Cloud Run](/docs/guides/google-cloud-run) - Deploy to Cloud Run with KeyEnv
### Container & Orchestration
- [Docker](/docs/guides/docker) - Use KeyEnv with Docker and docker-compose
- [Kubernetes](/docs/guides/kubernetes) - Sync secrets via External Secrets Operator (ESO)
### Infrastructure as Code
- [Terraform](/docs/guides/terraform) - Use KeyEnv secrets in Terraform configurations
## AI Coding Assistants
Use KeyEnv with Claude Code, Codex, Cursor, Gemini CLI, and other AI coding tools.
Source: https://keyenv.dev/docs/guides/ai-tools/
KeyEnv publishes [Agent Skills](https://agentskills.io/) so AI coding assistants can discover and use the `keyenv` CLI automatically. When your AI tool knows about KeyEnv, it can pull secrets, set environment variables, scan for leaks, and manage rotations on your behalf.
### Supported Tools
Agent Skills work with 35+ AI coding assistants:
| Tool | Support |
|------|---------|
| Claude Code | Agent Skills |
| OpenAI Codex | Agent Skills |
| Cursor | Agent Skills |
| Gemini CLI | Agent Skills |
| GitHub Copilot | Agent Skills |
| Windsurf | Agent Skills |
### Install Agent Skills
#### Automatic Installation
```bash
npx skills add keyenv/keyenv-skills
```
This installs all three KeyEnv skills:
| Skill | What It Teaches |
|-------|-----------------|
| `keyenv` | Core secrets management: auth, pull/push, set/get, list, diff, export, run |
| `keyenv-scan` | Scanning codebases for hardcoded secrets |
| `keyenv-rotate` | Database credential rotation management |
#### Manual Installation (Claude Code)
Copy the skill directories to your Claude Code skills folder:
```bash
# Clone the skills repo
git clone https://github.com/keyenv/keyenv-skills.git /tmp/keyenv-skills
# Copy skills
cp -r /tmp/keyenv-skills/keyenv ~/.claude/skills/keyenv
cp -r /tmp/keyenv-skills/keyenv-scan ~/.claude/skills/keyenv-scan
cp -r /tmp/keyenv-skills/keyenv-rotate ~/.claude/skills/keyenv-rotate
# Clean up
rm -rf /tmp/keyenv-skills
```
#### Manual Installation (Cursor)
Create a rule file at `.cursor/rules/keyenv.mdc`:
```yaml
---
description: Use the keyenv CLI to manage secrets and environment variables. Activate when the user mentions secrets, env vars, .env files, or keyenv.
alwaysApply: false
---
Use the `keyenv` CLI for secrets management. Key commands:
- `keyenv pull` - Pull secrets to .env
- `keyenv push` - Push .env to server
- `keyenv run -- ` - Run with injected secrets
- `keyenv set KEY VALUE` - Set a secret
- `keyenv get KEY` - Get a secret
- `keyenv diff` - Compare local vs remote
- `keyenv scan` - Scan for hardcoded secrets
All commands accept `-e ` for environment (default: development) and `--json` for machine-readable output.
```
---
### What Your AI Tool Can Do
Once the skills are installed, your AI coding assistant can:
**Manage secrets conversationally:**
- "Pull the production secrets"
- "Set the DATABASE_URL to postgres://..."
- "What secrets do we have in staging?"
- "Show me the history of the API_KEY"
**Run commands with secrets:**
- "Start the dev server with secrets injected"
- "Run the test suite with production config"
**Scan for security issues:**
- "Scan this repo for hardcoded secrets"
- "Set up a pre-commit hook to prevent secret leaks"
**Manage rotations:**
- "Show me the rotation status for production"
- "Trigger a manual rotation for main_db"
---
### Adding KeyEnv to Your Project Instructions
You can also add KeyEnv instructions directly to your project's AI configuration file.
#### CLAUDE.md (Claude Code)
Add to your project's `CLAUDE.md`:
```markdown
## Secrets Management
This project uses KeyEnv for secrets management.
- Pull secrets: `keyenv pull -e `
- Run with secrets: `keyenv run -- `
- Default environment: development
- Never commit .env files
```
#### AGENTS.md (Codex)
Add to your project's `AGENTS.md`:
```markdown
## Environment Variables
Use the `keyenv` CLI to manage secrets. Run `keyenv pull` to sync,
or `keyenv run -- ` to inject secrets without writing .env files.
```
---
### LLM-Friendly Documentation
KeyEnv provides machine-readable documentation for AI tools:
| File | URL | Purpose |
|------|-----|---------|
| `llms.txt` | [keyenv.dev/llms.txt](https://keyenv.dev/llms.txt) | Index of every docs page, product page, and blog post, with descriptions |
| `llms-full.txt` | [keyenv.dev/llms-full.txt](https://keyenv.dev/llms-full.txt) | The complete documentation as one markdown file |
| `openapi.yaml` | [keyenv.dev/openapi.yaml](https://keyenv.dev/openapi.yaml) | Machine-readable REST API specification |
| `openapi.json` | [keyenv.dev/openapi.json](https://keyenv.dev/openapi.json) | The same specification as JSON |
The first two follow the [llms.txt standard](https://llmstxt.org/). All four are regenerated from the docs and the OpenAPI spec on every build, so they never fall behind the site.
#### Raw markdown for any page
Append `.md` to any documentation URL to get the markdown source instead of rendered HTML. This is cheaper for an agent to read and keeps tables and code blocks intact:
```bash
curl https://keyenv.dev/docs/cli.md
curl https://keyenv.dev/docs/getting-started/first-project.md
curl https://keyenv.dev/docs/api/secrets.md
```
Every page also advertises its markdown twin in the HTML head:
```html
```
---
### Security Notes
AI coding assistants interact with KeyEnv through the CLI, which means:
- **Authentication is local.** Your AI tool uses your existing CLI session. No credentials are shared with AI providers.
- **Secrets stay local.** Values fetched by `keyenv get` or `keyenv pull` remain on your machine.
- **Audit trail preserved.** All operations are logged in the KeyEnv audit log, attributed to your user account.
- **Permissions enforced.** The AI tool has the same access level as your CLI session. Environment permissions still apply.
## CI/CD Integration
Integrate KeyEnv with your CI/CD pipeline.
Source: https://keyenv.dev/docs/guides/ci-cd/
This guide shows how to integrate KeyEnv with popular CI/CD platforms.
### Prerequisites
1. A KeyEnv project with secrets configured
2. A service token with access to the appropriate environment
### Creating a Service Token
1. Go to **Project Settings** → **Service Tokens**
2. Click **Create Token**
3. Name it after your CI/CD platform (e.g., "GitHub Actions - Production")
4. Select the environment (e.g., `production`)
5. Copy the token
### GitHub Actions
Add your service token to GitHub Secrets, then use it in your workflow:
```yaml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install KeyEnv
run: curl -fsSL https://keyenv.dev/install.sh | bash
- name: Pull secrets
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
run: keyenv pull -e production
- name: Deploy
run: |
# Your deployment commands
# Secrets are available in .env
```
#### Alternative: Inject at Runtime
```yaml
- name: Run with secrets
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
run: keyenv run -e production -- npm run deploy
```
### GitLab CI
Add the token as a CI/CD variable, then use it:
```yaml
deploy:
stage: deploy
image: ubuntu:latest
before_script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv pull -e production
- ./deploy.sh
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
only:
- main
```
### CircleCI
Use the official KeyEnv orb for the easiest integration:
```yaml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
jobs:
deploy:
docker:
- image: cimg/base:stable
steps:
- checkout
- keyenv/load:
environment: production
- run:
name: Deploy
command: ./deploy.sh
workflows:
deploy:
jobs:
- deploy:
filters:
branches:
only: main
```
For more detailed examples and options, see the [CircleCI Integration Guide](/docs/guides/circleci).
### Secret Scanning
KeyEnv can scan your codebase for hardcoded secrets before they reach production. Add secret scanning to your CI/CD pipeline to catch leaks early.
#### GitHub Actions
Use the official scan action:
```yaml
name: Security
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Scan for secrets
uses: keyenv/scan-action@v1
with:
severity: high
```
#### Other CI/CD Platforms
Use the CLI scanner:
```bash
# Install KeyEnv
curl -fsSL https://keyenv.dev/install.sh | bash
# Scan for secrets
keyenv scan --severity high
```
The scanner detects 149+ secret patterns including AWS keys, GitHub tokens, Stripe keys, database passwords, and more.
> **Tip**
>
> Enable the **Scan for secrets** toggle in the KeyEnv dashboard integrations page to automatically add scanning to your generated workflow configurations.
For complete scanning documentation, see the [Secret Scanner Action](/docs/sdks/scan-action).
### Best Practices
1. **Scan for hardcoded secrets** - Add `keyenv scan` or the scan action to catch leaks before they're merged
2. **Use environment-specific tokens** - Create separate tokens for staging and production
3. **Limit token scope** - Only grant access to the environments needed
4. **Don't log secrets** - Avoid echoing secret values in CI logs
5. **Use `keyenv run`** - When possible, inject secrets at runtime instead of writing to disk
> **Warning**
>
> Never commit service tokens to your repository. Always use your CI/CD platform's secret management.
## GitLab CI/CD
Integrate KeyEnv with GitLab CI/CD pipelines.
Source: https://keyenv.dev/docs/guides/gitlab-ci/
This guide shows how to use KeyEnv secrets in your GitLab CI/CD pipelines.
### Overview
There are two approaches to integrate KeyEnv with GitLab CI/CD:
| Method | Best For | Dependencies |
|--------|----------|--------------|
| **CLI-based** | Full features | KeyEnv CLI |
| **curl-based** | Minimal images | curl, jq |
Both approaches use a service token stored as a GitLab CI/CD variable.
### Prerequisites
1. A KeyEnv project with secrets configured
2. A service token with access to the appropriate environment
3. A GitLab repository with CI/CD enabled
---
### Creating a Service Token
1. Go to your KeyEnv dashboard
2. Navigate to **Project Settings** > **Service Tokens**
3. Click **Create Token**
4. Name it "GitLab CI - Production" (or the appropriate environment)
5. Select the environment (e.g., `production`)
6. Copy the token
### Adding the Token to GitLab
1. Go to your GitLab repository
2. Navigate to **Settings** > **CI/CD** > **Variables**
3. Click **Add variable**
4. Configure the variable:
- **Key**: `KEYENV_TOKEN`
- **Value**: Your service token
- **Type**: Variable
- **Flags**: Check **Mask variable** and optionally **Protect variable**
5. Click **Add variable**
> **Note**
>
> Use **Protected variables** to limit token access to protected branches only.
---
### Option 1: CLI-Based Integration
Install the KeyEnv CLI during your pipeline and use it to fetch secrets.
#### Basic Example
```yaml
# .gitlab-ci.yml
stages:
- deploy
deploy:
stage: deploy
image: ubuntu:latest
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv pull -e production
- source .env
- ./deploy.sh
only:
- main
```
#### Using keyenv run
Inject secrets directly into your command without writing to disk:
```yaml
# .gitlab-ci.yml
deploy:
stage: deploy
image: ubuntu:latest
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv run -e production -- ./deploy.sh
only:
- main
```
#### Reusable Template
Create a reusable template for multiple jobs:
```yaml
# .gitlab-ci.yml
.keyenv_setup:
before_script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
stages:
- test
- deploy
test:
extends: .keyenv_setup
stage: test
image: ubuntu:latest
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
script:
- keyenv pull -e development
- npm ci
- npm test
deploy_staging:
extends: .keyenv_setup
stage: deploy
image: ubuntu:latest
environment:
name: staging
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
script:
- keyenv run -e staging -- ./deploy.sh
only:
- develop
deploy_production:
extends: .keyenv_setup
stage: deploy
image: ubuntu:latest
environment:
name: production
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
script:
- keyenv run -e production -- ./deploy.sh
only:
- main
```
#### Dynamic Environment Selection
Use GitLab's `$CI_ENVIRONMENT_NAME` variable for automatic environment mapping:
```yaml
# .gitlab-ci.yml
deploy:
stage: deploy
image: ubuntu:latest
environment:
name: $CI_COMMIT_REF_NAME
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv pull -e $CI_ENVIRONMENT_NAME
- ./deploy.sh
```
---
### Option 2: curl-Based Integration
Fetch secrets via the API without installing the CLI. Useful for minimal Docker images.
#### Basic Example
```yaml
# .gitlab-ci.yml
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
KEYENV_PROJECT: "YOUR_PROJECT_ID"
KEYENV_ENV: "production"
deploy:
image: alpine:latest
before_script:
- apk add --no-cache curl jq
script:
- |
# Fetch secrets from KeyEnv API
SECRETS=$(curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"https://api.keyenv.dev/api/v1/projects/$KEYENV_PROJECT/environments/$KEYENV_ENV/secrets/export")
# Export each secret as an environment variable
for row in $(echo "$SECRETS" | jq -c '.secrets[]'); do
key=$(echo $row | jq -r '.key')
value=$(echo $row | jq -r '.value')
export "$key=$value"
done
# Run your commands with secrets available
./deploy.sh
only:
- main
```
#### Reusable Template
```yaml
# .gitlab-ci.yml
.keyenv_curl:
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
KEYENV_PROJECT: "YOUR_PROJECT_ID"
before_script:
- apk add --no-cache curl jq
- |
SECRETS=$(curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"https://api.keyenv.dev/api/v1/projects/$KEYENV_PROJECT/environments/$KEYENV_ENV/secrets/export")
for row in $(echo "$SECRETS" | jq -c '.secrets[]'); do
key=$(echo $row | jq -r '.key')
value=$(echo $row | jq -r '.value')
export "$key=$value"
done
deploy_staging:
extends: .keyenv_curl
image: alpine:latest
variables:
KEYENV_ENV: "staging"
script:
- ./deploy.sh
only:
- develop
deploy_production:
extends: .keyenv_curl
image: alpine:latest
variables:
KEYENV_ENV: "production"
script:
- ./deploy.sh
only:
- main
```
#### Writing to a .env File
If your application needs a `.env` file:
```yaml
# .gitlab-ci.yml
deploy:
image: alpine:latest
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
KEYENV_PROJECT: "YOUR_PROJECT_ID"
before_script:
- apk add --no-cache curl jq
- |
curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"https://api.keyenv.dev/api/v1/projects/$KEYENV_PROJECT/environments/production/secrets/export" \
| jq -r '.secrets[] | "\(.key)=\(.value)"' > .env
script:
- source .env
- ./deploy.sh
only:
- main
```
---
### Docker Workflows
#### Docker Build with Secrets
```yaml
# .gitlab-ci.yml
build:
stage: build
image: docker:latest
services:
- docker:dind
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apk add --no-cache curl bash
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv pull -e production -o .env.production
- docker build --secret id=env,src=.env.production -t myapp:$CI_COMMIT_SHA .
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
only:
- main
```
#### Docker Compose Deployment
```yaml
# .gitlab-ci.yml
deploy:
stage: deploy
image: docker:latest
services:
- docker:dind
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apk add --no-cache curl bash docker-compose
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv pull -e production
- docker-compose up -d
only:
- main
```
---
### Language-Specific Examples
#### Node.js Application
```yaml
# .gitlab-ci.yml
stages:
- test
- deploy
test:
stage: test
image: node:20-alpine
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apk add --no-cache curl bash
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
- keyenv pull -e development
script:
- npm ci
- npm test
- npm run build
deploy:
stage: deploy
image: node:20-alpine
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apk add --no-cache curl bash
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv run -e production -- npm run deploy
only:
- main
```
#### Python Application
```yaml
# .gitlab-ci.yml
stages:
- test
- deploy
test:
stage: test
image: python:3.12-slim
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
- keyenv pull -e development
script:
- pip install -r requirements.txt
- pytest
deploy:
stage: deploy
image: python:3.12-slim
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv run -e production -- python deploy.py
only:
- main
```
#### Go Application
```yaml
# .gitlab-ci.yml
stages:
- test
- build
test:
stage: test
image: golang:1.22-alpine
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apk add --no-cache curl bash
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
- keyenv pull -e development
script:
- go test ./...
build:
stage: build
image: golang:1.22-alpine
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
before_script:
- apk add --no-cache curl bash
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv run -e production -- go build -o app .
artifacts:
paths:
- app
only:
- main
```
---
### Security Best Practices
1. **Use protected variables** - Mark `KEYENV_TOKEN` as protected to limit access to protected branches
2. **Use masked variables** - Always mask the token to prevent exposure in logs
3. **Scope tokens narrowly** - Create separate tokens for each environment
4. **Don't log secrets** - Avoid `echo $SECRET` in your scripts
5. **Use `keyenv run`** - Prefer runtime injection over writing to disk
6. **Limit job access** - Use `only` and `except` to control which jobs run
> **Warning**
>
> Never commit service tokens to your repository. Always use GitLab CI/CD variables.
---
### Troubleshooting
#### "keyenv: command not found"
Ensure the PATH is updated after installation:
```yaml
before_script:
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH" # Required!
```
#### "Authentication failed"
- Verify your token is correct in GitLab CI/CD variables
- Check the token hasn't expired
- Ensure the variable is not protected if running on unprotected branches
#### "Access denied"
- The token may not have access to the specified project
- The token may not have access to the specified environment
- Check token permissions in KeyEnv dashboard
#### "curl: command not found"
Install curl in your Docker image:
```yaml
# For Alpine
before_script:
- apk add --no-cache curl
# For Debian/Ubuntu
before_script:
- apt-get update && apt-get install -y curl
```
#### "jq: command not found" (curl-based approach)
Install jq in your Docker image:
```yaml
# For Alpine
before_script:
- apk add --no-cache curl jq
# For Debian/Ubuntu
before_script:
- apt-get update && apt-get install -y curl jq
```
#### Secrets not available in subsequent steps
Environment variables set with `export` in `before_script` are available in `script` but not in `after_script` or other jobs. For sharing between jobs, use artifacts or GitLab CI/CD variables.
---
### Self-Hosted KeyEnv
If you're running a self-hosted KeyEnv instance:
```yaml
# .gitlab-ci.yml
variables:
KEYENV_API_URL: https://keyenv.your-company.com
deploy:
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
script:
- keyenv pull -e production
- ./deploy.sh
```
For curl-based integration, update the API URL:
```yaml
# .gitlab-ci.yml
variables:
KEYENV_API_URL: https://keyenv.your-company.com
KEYENV_PROJECT: "YOUR_PROJECT_ID"
deploy:
before_script:
- apk add --no-cache curl jq
- |
SECRETS=$(curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"$KEYENV_API_URL/api/v1/projects/$KEYENV_PROJECT/environments/$KEYENV_ENV/secrets/export")
# ... rest of script
```
---
### Complete Example
Here's a complete `.gitlab-ci.yml` for a typical Node.js application:
```yaml
# .gitlab-ci.yml
# Define stages
stages:
- test
- build
- deploy
# Reusable KeyEnv setup
.keyenv_setup:
before_script:
- apk add --no-cache curl bash
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
# Variables (set KEYENV_TOKEN in GitLab CI/CD settings)
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
# Test job
test:
extends: .keyenv_setup
stage: test
image: node:20-alpine
script:
- keyenv pull -e development
- npm ci
- npm test
coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'
# Build job
build:
extends: .keyenv_setup
stage: build
image: node:20-alpine
script:
- keyenv pull -e staging
- npm ci
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 hour
only:
- develop
- main
# Deploy to staging
deploy_staging:
extends: .keyenv_setup
stage: deploy
image: node:20-alpine
environment:
name: staging
url: https://staging.example.com
script:
- keyenv run -e staging -- npm run deploy:staging
only:
- develop
# Deploy to production
deploy_production:
extends: .keyenv_setup
stage: deploy
image: node:20-alpine
environment:
name: production
url: https://example.com
script:
- keyenv run -e production -- npm run deploy:production
only:
- main
when: manual
```
#### GitLab CI/CD Variables
Add these variables in **Settings** > **CI/CD** > **Variables**:
| Variable | Value | Protected | Masked |
|----------|-------|-----------|--------|
| `KEYENV_TOKEN` | `srv_your_token_here` | Yes (optional) | Yes |
#### KeyEnv Environments
Create environments in KeyEnv matching your deployment stages:
| Environment | Purpose |
|-------------|---------|
| `development` | Testing with test data |
| `staging` | Pre-production validation |
| `production` | Live production deployment |
## CircleCI Integration
Load KeyEnv secrets into your CircleCI workflows using the official orb.
Source: https://keyenv.dev/docs/guides/circleci/
Load secrets from KeyEnv into your CircleCI workflows using the official KeyEnv orb or CLI.
### Overview
There are two ways to integrate KeyEnv with CircleCI:
| Method | Best For | Setup |
|--------|----------|-------|
| **KeyEnv Orb** | Most projects | Simplest setup |
| **CLI-based** | Custom requirements | More control |
### Features
- Exports secrets as environment variables
- Optionally writes secrets to a `.env` file
- Supports project-scoped service tokens
- Works with self-hosted KeyEnv instances
- Zero dependencies (auto-installs required tools)
---
### Option 1: Using the KeyEnv Orb (Recommended)
The official KeyEnv orb provides the simplest integration.
#### Basic Usage
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
jobs:
build:
docker:
- image: cimg/node:20.0
steps:
- checkout
- keyenv/load:
environment: production
- run: npm test
```
#### Orb Parameters
| Parameter | Description | Required | Default |
|-----------|-------------|----------|---------|
| `environment` | Environment name (e.g., `production`) | Yes | - |
| `project-id` | Project ID. Optional if using project-scoped token. | No | - |
| `token-var` | Name of env var containing the token | No | `KEYENV_TOKEN` |
| `api-url` | KeyEnv API URL | No | `https://api.keyenv.dev` |
| `env-file` | Path to write `.env` file | No | - |
#### With Project ID
If your service token isn't project-scoped, specify the project:
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
jobs:
build:
docker:
- image: cimg/node:20.0
steps:
- checkout
- keyenv/load:
environment: staging
project-id: proj_abc123def456
- run: npm test
```
#### Write to .env File
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
jobs:
build:
docker:
- image: cimg/node:20.0
steps:
- checkout
- keyenv/load:
environment: production
env-file: .env
- run: |
# Secrets are available as env vars AND in .env file
npm test
```
#### Multi-Environment Workflow
Use different environments for different jobs:
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
jobs:
test:
docker:
- image: cimg/node:20.0
steps:
- checkout
- keyenv/load:
environment: development
- run: npm ci
- run: npm test
deploy:
docker:
- image: cimg/node:20.0
steps:
- checkout
- keyenv/load:
environment: production
- run: npm run deploy
workflows:
build-and-deploy:
jobs:
- test
- deploy:
requires:
- test
filters:
branches:
only: main
```
#### Using a Context
Store your `KEYENV_TOKEN` in a CircleCI context for use across multiple projects:
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
jobs:
deploy:
docker:
- image: cimg/node:20.0
steps:
- checkout
- keyenv/load:
environment: production
- run: npm run deploy
workflows:
deploy:
jobs:
- deploy:
context: keyenv-secrets
```
#### Using the load-and-run Job
For simple workflows, use the built-in job:
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
workflows:
deploy:
jobs:
- keyenv/load-and-run:
environment: production
command: npm run deploy
context: keyenv-secrets
```
---
### Option 2: CLI-Based Integration
Install the KeyEnv CLI directly in your workflow for more control.
#### Basic Example
```yaml
# .circleci/config.yml
version: 2.1
jobs:
deploy:
docker:
- image: cimg/base:stable
steps:
- checkout
- run:
name: Install KeyEnv CLI
command: |
curl -fsSL https://keyenv.dev/install.sh | bash
echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV
- run:
name: Pull secrets
command: keyenv pull -e production
- run:
name: Deploy
command: ./deploy.sh
workflows:
deploy:
jobs:
- deploy:
filters:
branches:
only: main
```
#### Using keyenv run
Inject secrets directly without writing to disk:
```yaml
# .circleci/config.yml
version: 2.1
jobs:
deploy:
docker:
- image: cimg/base:stable
steps:
- checkout
- run:
name: Install KeyEnv CLI
command: |
curl -fsSL https://keyenv.dev/install.sh | bash
echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV
- run:
name: Deploy with secrets
command: keyenv run -e production -- ./deploy.sh
workflows:
deploy:
jobs:
- deploy:
filters:
branches:
only: main
```
#### Reusable Commands
```yaml
# .circleci/config.yml
version: 2.1
commands:
install-keyenv:
description: Install KeyEnv CLI
steps:
- run:
name: Install KeyEnv CLI
command: |
curl -fsSL https://keyenv.dev/install.sh | bash
echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV
load-secrets:
description: Load secrets from KeyEnv
parameters:
environment:
type: string
default: "production"
steps:
- run:
name: Pull secrets
command: keyenv pull -e << parameters.environment >>
jobs:
test:
docker:
- image: cimg/node:20.0
steps:
- checkout
- install-keyenv
- load-secrets:
environment: development
- run: npm ci
- run: npm test
deploy:
docker:
- image: cimg/node:20.0
steps:
- checkout
- install-keyenv
- run:
name: Deploy
command: keyenv run -e production -- npm run deploy
workflows:
build-and-deploy:
jobs:
- test
- deploy:
requires:
- test
filters:
branches:
only: main
```
---
### Language-Specific Examples
#### Node.js Application
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
node: circleci/node@5.0
jobs:
test:
docker:
- image: cimg/node:20.0
steps:
- checkout
- node/install-packages
- keyenv/load:
environment: development
- run: npm test
- run: npm run build
workflows:
ci:
jobs:
- test
```
#### Python Application
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
python: circleci/python@2.0
jobs:
test:
docker:
- image: cimg/python:3.12
steps:
- checkout
- python/install-packages
- keyenv/load:
environment: development
- run: pytest
workflows:
ci:
jobs:
- test
```
#### Go Application
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
go: circleci/go@1.7
jobs:
test:
docker:
- image: cimg/go:1.22
steps:
- checkout
- go/load-cache
- go/mod-download
- keyenv/load:
environment: development
- run: go test ./...
- go/save-cache
workflows:
ci:
jobs:
- test
```
#### Docker Build with Secrets
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
jobs:
build:
docker:
- image: cimg/base:stable
steps:
- checkout
- setup_remote_docker
- keyenv/load:
environment: production
env-file: .env.production
- run: |
docker build \
--secret id=env,src=.env.production \
-t myapp:latest .
workflows:
build:
jobs:
- build
```
---
### Setting Up Your Token
#### Create a Service Token
1. Go to your KeyEnv dashboard
2. Navigate to **Settings > Service Tokens**
3. Create a new token with:
- **Scope**: Select your project (recommended)
- **Permissions**: `secrets:read`
4. Copy the token
#### Add Token to CircleCI
**Option A: Project Environment Variable**
1. Go to your CircleCI project
2. Navigate to **Project Settings** > **Environment Variables**
3. Add a new variable:
- Name: `KEYENV_TOKEN`
- Value: Your service token
**Option B: Context (Recommended for multiple projects)**
1. Go to **Organization Settings** > **Contexts**
2. Create a new context (e.g., `keyenv-secrets`)
3. Add a variable:
- Name: `KEYENV_TOKEN`
- Value: Your service token
4. Use the context in your workflow:
```yaml
workflows:
deploy:
jobs:
- deploy:
context: keyenv-secrets
```
---
### Self-Hosted KeyEnv
If you're running a self-hosted KeyEnv instance:
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
jobs:
deploy:
docker:
- image: cimg/node:20.0
steps:
- checkout
- keyenv/load:
environment: production
api-url: https://keyenv.your-company.com
- run: npm run deploy
```
For CLI-based integration:
```yaml
# .circleci/config.yml
version: 2.1
jobs:
deploy:
docker:
- image: cimg/base:stable
environment:
KEYENV_API_URL: https://keyenv.your-company.com
steps:
- checkout
- run:
name: Install KeyEnv CLI
command: |
curl -fsSL https://keyenv.dev/install.sh | bash
echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV
- run:
name: Deploy
command: keyenv run -e production -- ./deploy.sh
```
---
### Security Best Practices
1. **Use contexts** - Centralize token management across projects
2. **Scope tokens narrowly** - Create separate tokens for each environment
3. **Don't log secrets** - Avoid `echo $SECRET` in your scripts
4. **Use `keyenv run`** - Prefer runtime injection over writing to disk
5. **Restrict context access** - Limit which projects can use each context
> **Warning**
>
> Never commit service tokens to your repository. Always use CircleCI's environment variables or contexts.
---
### Troubleshooting
#### "Authentication failed"
- Verify your token is correct in CircleCI project settings
- Check the token hasn't expired
- Ensure the environment variable name matches `token-var` parameter
#### "Access denied"
- The token may not have access to the specified project
- The token may not have access to the specified environment
- Check token permissions in KeyEnv dashboard
#### "Project or environment not found"
- Verify the `project-id` is correct
- Verify the `environment` name matches exactly (case-sensitive)
- Check the project/environment exists in KeyEnv
#### Secrets not available in subsequent steps
- Ensure you're using a bash-based executor (most CircleCI images work)
- Secrets are exported to `$BASH_ENV` and loaded automatically in subsequent steps
- If using a custom shell, source `$BASH_ENV` manually
#### "keyenv: command not found"
Ensure the PATH is updated correctly:
```yaml
- run:
name: Install KeyEnv CLI
command: |
curl -fsSL https://keyenv.dev/install.sh | bash
echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV
```
---
### Complete Example
Here's a complete CircleCI configuration for a Node.js application:
```yaml
# .circleci/config.yml
version: 2.1
orbs:
keyenv: keyenv/secrets@1.0
node: circleci/node@5.0
jobs:
test:
docker:
- image: cimg/node:20.0
steps:
- checkout
- node/install-packages
- keyenv/load:
environment: development
- run:
name: Run tests
command: npm test
- run:
name: Run linter
command: npm run lint
- store_test_results:
path: test-results
build:
docker:
- image: cimg/node:20.0
steps:
- checkout
- node/install-packages
- keyenv/load:
environment: staging
- run:
name: Build application
command: npm run build
- persist_to_workspace:
root: .
paths:
- dist
deploy_staging:
docker:
- image: cimg/node:20.0
steps:
- checkout
- attach_workspace:
at: .
- keyenv/load:
environment: staging
- run:
name: Deploy to staging
command: npm run deploy:staging
deploy_production:
docker:
- image: cimg/node:20.0
steps:
- checkout
- attach_workspace:
at: .
- keyenv/load:
environment: production
- run:
name: Deploy to production
command: npm run deploy:production
workflows:
build-test-deploy:
jobs:
- test
- build:
requires:
- test
- deploy_staging:
requires:
- build
filters:
branches:
only: develop
context: keyenv-secrets
- deploy_production:
requires:
- build
filters:
branches:
only: main
context: keyenv-secrets
```
#### CircleCI Context Setup
Create a context named `keyenv-secrets`:
| Variable | Value |
|----------|-------|
| `KEYENV_TOKEN` | `srv_your_token_here` |
#### KeyEnv Environments
Create environments in KeyEnv:
| Environment | Purpose |
|-------------|---------|
| `development` | Testing with test data |
| `staging` | Pre-production validation |
| `production` | Live production deployment |
---
### Additional Resources
- [CircleCI Orb Registry](https://circleci.com/developer/orbs/orb/keyenv/secrets)
- [CircleCI Orb Documentation](https://circleci.com/docs/orb-intro/)
- [KeyEnv GitHub Action](/docs/sdks/github-action) - Similar integration for GitHub Actions
## Azure Pipelines
Load KeyEnv secrets in Azure DevOps pipelines.
Source: https://keyenv.dev/docs/guides/azure-pipelines/
Load KeyEnv secrets in your Azure DevOps CI/CD pipelines.
### Prerequisites
- Azure DevOps project with Pipelines enabled
- KeyEnv service token with read access
### Setup
#### 1. Add Your Token
##### Option A: Pipeline Variable
1. Edit your pipeline in Azure DevOps
2. Click **Variables**
3. Add `KEYENV_TOKEN` with your service token
4. Check **Keep this value secret**
##### Option B: Variable Group
1. Go to **Pipelines** > **Library**
2. Create a new Variable group
3. Add `KEYENV_TOKEN` as a secret variable
4. Link the group to your pipeline
#### 2. Configure azure-pipelines.yml
```yaml
trigger:
- main
pool:
vmImage: 'ubuntu-latest'
variables:
- group: keyenv-secrets # If using variable group
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: curl -fsSL https://keyenv.dev/install.sh | bash
displayName: 'Install KeyEnv CLI'
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm ci
displayName: 'Install dependencies'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm test
displayName: 'Run tests'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm run build
displayName: 'Build'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
### Environment Mapping
Map branches to KeyEnv environments:
```yaml
variables:
${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
keyenvEnv: 'production'
${{ if eq(variables['Build.SourceBranch'], 'refs/heads/staging') }}:
keyenvEnv: 'staging'
${{ else }}:
keyenvEnv: 'development'
steps:
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e $(keyenvEnv) -- npm test
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
### Multi-Stage Pipeline
```yaml
trigger:
- main
- staging
stages:
- stage: Test
jobs:
- job: Test
pool:
vmImage: 'ubuntu-latest'
steps:
- script: curl -fsSL https://keyenv.dev/install.sh | bash
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e development -- npm test
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
- stage: Deploy
condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
jobs:
- deployment: Production
environment: 'production'
strategy:
runOnce:
deploy:
steps:
- script: curl -fsSL https://keyenv.dev/install.sh | bash
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm run deploy
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
### Pull Secrets to .env File
```yaml
steps:
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv pull -p YOUR_PROJECT_ID -e production -o .env
displayName: 'Pull secrets'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
- script: |
source .env
npm run build
displayName: 'Build with secrets'
```
### Template Usage
Create a reusable template:
```yaml
# templates/with-keyenv.yml
parameters:
- name: projectId
type: string
- name: environment
type: string
- name: command
type: string
steps:
- script: |
if [ ! -f "$HOME/.keyenv/bin/keyenv" ]; then
curl -fsSL https://keyenv.dev/install.sh | bash
fi
displayName: 'Install KeyEnv CLI'
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p ${{ parameters.projectId }} -e ${{ parameters.environment }} -- ${{ parameters.command }}
displayName: 'Run with KeyEnv'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
Use the template:
```yaml
steps:
- template: templates/with-keyenv.yml
parameters:
projectId: 'my-project'
environment: 'production'
command: 'npm test'
```
### Docker Builds
```yaml
steps:
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
eval $(keyenv export -p YOUR_PROJECT_ID -e production --format shell)
docker build \
--build-arg DATABASE_URL=$DATABASE_URL \
--build-arg API_KEY=$API_KEY \
-t myapp:$(Build.BuildId) .
displayName: 'Build Docker image'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
### Azure Container Apps
Deploy to Azure Container Apps with secrets:
```yaml
steps:
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
# Export secrets
keyenv export -p YOUR_PROJECT_ID -e production --format json > secrets.json
# Update Container App
az containerapp update \
--name myapp \
--resource-group mygroup \
--set-env-vars $(jq -r '.secrets[] | "\(.key)=\(.value)"' secrets.json | tr '\n' ' ')
displayName: 'Deploy to Container Apps'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
### Caching
Cache the CLI installation:
```yaml
variables:
KEYENV_CACHE_KEY: 'keyenv-cli-v1'
steps:
- task: Cache@2
inputs:
key: '$(KEYENV_CACHE_KEY)'
path: '$(HOME)/.keyenv'
displayName: 'Cache KeyEnv CLI'
- script: |
if [ ! -f "$HOME/.keyenv/bin/keyenv" ]; then
curl -fsSL https://keyenv.dev/install.sh | bash
fi
displayName: 'Install KeyEnv CLI'
```
### Full Example
```yaml
trigger:
- main
- staging
pool:
vmImage: 'ubuntu-latest'
variables:
- group: keyenv-secrets
- name: keyenvProject
value: 'your-project-id'
stages:
- stage: Build
jobs:
- job: BuildAndTest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
- task: Cache@2
inputs:
key: 'keyenv-cli-v1'
path: '$(HOME)/.keyenv'
- script: |
if [ ! -f "$HOME/.keyenv/bin/keyenv" ]; then
curl -fsSL https://keyenv.dev/install.sh | bash
fi
displayName: 'Install KeyEnv CLI'
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p $(keyenvProject) -e development -- npm ci
keyenv run -p $(keyenvProject) -e development -- npm test
keyenv run -p $(keyenvProject) -e development -- npm run build
displayName: 'Build and Test'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
- stage: DeployProduction
condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
jobs:
- deployment: Production
environment: 'production'
strategy:
runOnce:
deploy:
steps:
- script: curl -fsSL https://keyenv.dev/install.sh | bash
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p $(keyenvProject) -e production -- npm run deploy
displayName: 'Deploy'
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
### Troubleshooting
#### Variable Not Found
Ensure the variable is marked as secret and passed via `env`:
```yaml
- script: echo "Token exists: $([ -n "$KEYENV_TOKEN" ] && echo yes || echo no)"
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
#### Permission Denied
Check your service token permissions:
```yaml
- script: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv whoami
env:
KEYENV_TOKEN: $(KEYENV_TOKEN)
```
## Jenkins
Load KeyEnv secrets in Jenkins pipelines.
Source: https://keyenv.dev/docs/guides/jenkins/
Load KeyEnv secrets in your Jenkins CI/CD pipelines.
### Prerequisites
- Jenkins with Pipeline plugin
- KeyEnv service token with read access
### Setup
#### 1. Store Your Token
Add your KeyEnv token to Jenkins credentials:
1. Go to **Manage Jenkins** > **Credentials**
2. Select the appropriate scope (global or folder)
3. Click **Add Credentials**
4. Choose **Secret text**
5. Set ID to `keyenv-token`
6. Paste your KeyEnv service token
#### 2. Create Pipeline
##### Declarative Pipeline
```groovy
pipeline {
agent any
environment {
KEYENV_TOKEN = credentials('keyenv-token')
}
stages {
stage('Setup') {
steps {
sh '''
curl -fsSL https://keyenv.dev/install.sh | bash
export PATH="$HOME/.keyenv/bin:$PATH"
'''
}
}
stage('Build') {
steps {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm ci
keyenv run -p YOUR_PROJECT_ID -e production -- npm run build
'''
}
}
stage('Test') {
steps {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm test
'''
}
}
stage('Deploy') {
when {
branch 'main'
}
steps {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm run deploy
'''
}
}
}
}
```
##### Scripted Pipeline
```groovy
node {
withCredentials([string(credentialsId: 'keyenv-token', variable: 'KEYENV_TOKEN')]) {
stage('Setup') {
sh 'curl -fsSL https://keyenv.dev/install.sh | bash'
}
stage('Build') {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm ci
keyenv run -p YOUR_PROJECT_ID -e production -- npm run build
'''
}
stage('Test') {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e production -- npm test
'''
}
}
}
```
### Environment-Based Deployment
Map Jenkins branches to KeyEnv environments:
```groovy
pipeline {
agent any
environment {
KEYENV_TOKEN = credentials('keyenv-token')
KEYENV_ENV = "${env.BRANCH_NAME == 'main' ? 'production' : 'staging'}"
}
stages {
stage('Deploy') {
steps {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e $KEYENV_ENV -- npm run deploy
'''
}
}
}
}
```
### Pull Secrets to .env File
If you need a `.env` file instead of injecting directly:
```groovy
stage('Setup Secrets') {
steps {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv pull -p YOUR_PROJECT_ID -e production -o .env
'''
}
}
```
### Multi-Branch Pipeline
```groovy
pipeline {
agent any
environment {
KEYENV_TOKEN = credentials('keyenv-token')
}
stages {
stage('Determine Environment') {
steps {
script {
env.KEYENV_ENV = sh(
script: '''
case "$BRANCH_NAME" in
main) echo "production" ;;
staging) echo "staging" ;;
*) echo "development" ;;
esac
''',
returnStdout: true
).trim()
}
}
}
stage('Build & Test') {
steps {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv run -p YOUR_PROJECT_ID -e $KEYENV_ENV -- npm ci
keyenv run -p YOUR_PROJECT_ID -e $KEYENV_ENV -- npm test
'''
}
}
}
}
```
### Docker Builds
Pass secrets to Docker builds:
```groovy
stage('Docker Build') {
steps {
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
# Export secrets as build args
eval $(keyenv export -p YOUR_PROJECT_ID -e production --format shell)
docker build \
--build-arg DATABASE_URL=$DATABASE_URL \
--build-arg API_KEY=$API_KEY \
-t myapp:latest .
'''
}
}
```
### Shared Library
Create a reusable function in a Jenkins shared library:
```groovy
// vars/withKeyEnv.groovy
def call(String projectId, String environment, Closure body) {
withCredentials([string(credentialsId: 'keyenv-token', variable: 'KEYENV_TOKEN')]) {
sh 'curl -fsSL https://keyenv.dev/install.sh | bash 2>/dev/null || true'
sh """
export PATH="\$HOME/.keyenv/bin:\$PATH"
keyenv run -p ${projectId} -e ${environment} -- ${body()}
"""
}
}
```
Usage:
```groovy
pipeline {
stages {
stage('Test') {
steps {
withKeyEnv('my-project', 'staging') {
'npm test'
}
}
}
}
}
```
### Security Best Practices
1. **Use credentials binding** - Never hardcode tokens in Jenkinsfiles
2. **Limit token scope** - Create project-specific tokens
3. **Mask secrets in logs** - Jenkins masks `credentials()` values automatically
4. **Use folder-scoped credentials** - Limit access to specific projects
### Troubleshooting
#### CLI Not Found
Ensure the PATH is set in every stage:
```groovy
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv --version
'''
```
#### Token Not Working
Verify the credential is accessible:
```groovy
withCredentials([string(credentialsId: 'keyenv-token', variable: 'KEYENV_TOKEN')]) {
sh 'echo "Token length: ${#KEYENV_TOKEN}"'
}
```
#### Permission Denied
Check your service token has access to the project and environment:
```groovy
sh '''
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv whoami # Shows token info
'''
```
## Travis CI
Load KeyEnv secrets in Travis CI builds.
Source: https://keyenv.dev/docs/guides/travis-ci/
Load KeyEnv secrets in your Travis CI builds.
### Prerequisites
- Travis CI account connected to your repository
- KeyEnv service token with read access
### Setup
#### 1. Add Your Token
1. Go to your repository settings in Travis CI
2. Navigate to **Environment Variables**
3. Add `KEYENV_TOKEN` with your service token
4. Ensure **Display value in build log** is OFF
#### 2. Configure .travis.yml
```yaml
language: node_js
node_js:
- "20"
before_install:
- curl -fsSL https://keyenv.dev/install.sh | bash
- export PATH="$HOME/.keyenv/bin:$PATH"
script:
- keyenv run -p YOUR_PROJECT_ID -e $TRAVIS_BRANCH -- npm ci
- keyenv run -p YOUR_PROJECT_ID -e $TRAVIS_BRANCH -- npm test
deploy:
provider: script
script: keyenv run -p YOUR_PROJECT_ID -e production -- npm run deploy
on:
branch: main
```
### Environment Mapping
Map Travis CI branches to KeyEnv environments:
```yaml
env:
global:
- KEYENV_PROJECT=your-project-id
before_script:
- |
case "$TRAVIS_BRANCH" in
main)
export KEYENV_ENV=production
;;
staging)
export KEYENV_ENV=staging
;;
*)
export KEYENV_ENV=development
;;
esac
script:
- keyenv run -p $KEYENV_PROJECT -e $KEYENV_ENV -- npm test
```
### Build Stages
```yaml
stages:
- test
- name: deploy
if: branch = main
jobs:
include:
- stage: test
script:
- keyenv run -p YOUR_PROJECT_ID -e development -- npm test
- stage: deploy
script:
- keyenv run -p YOUR_PROJECT_ID -e production -- npm run deploy
```
### Pull Secrets to .env File
```yaml
before_script:
- keyenv pull -p YOUR_PROJECT_ID -e $KEYENV_ENV -o .env
script:
- source .env
- npm test
```
### Matrix Builds
Test across multiple environments:
```yaml
jobs:
include:
- name: "Test Development"
env: KEYENV_ENV=development
- name: "Test Staging"
env: KEYENV_ENV=staging
script:
- keyenv run -p YOUR_PROJECT_ID -e $KEYENV_ENV -- npm test
```
### Docker Builds
```yaml
services:
- docker
script:
- |
eval $(keyenv export -p YOUR_PROJECT_ID -e production --format shell)
docker build \
--build-arg DATABASE_URL=$DATABASE_URL \
--build-arg API_KEY=$API_KEY \
-t myapp:$TRAVIS_COMMIT .
```
### Caching CLI Installation
Speed up builds by caching the CLI:
```yaml
cache:
directories:
- $HOME/.keyenv
before_install:
- |
if [ ! -f "$HOME/.keyenv/bin/keyenv" ]; then
curl -fsSL https://keyenv.dev/install.sh | bash
fi
- export PATH="$HOME/.keyenv/bin:$PATH"
```
### Pull Requests
For PR builds, use a development environment:
```yaml
script:
- |
if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then
KEYENV_ENV=development
else
KEYENV_ENV=$TRAVIS_BRANCH
fi
keyenv run -p YOUR_PROJECT_ID -e $KEYENV_ENV -- npm test
```
### Encrypted Environment Variables
If you prefer to encrypt your token in `.travis.yml`:
```bash
# Install Travis CLI
gem install travis
# Encrypt your token
travis encrypt KEYENV_TOKEN=your-token --add
```
This adds to your `.travis.yml`:
```yaml
env:
global:
secure: "encrypted-string..."
```
### Full Example
```yaml
language: node_js
node_js:
- "20"
cache:
directories:
- node_modules
- $HOME/.keyenv
env:
global:
- KEYENV_PROJECT=your-project-id
before_install:
- |
if [ ! -f "$HOME/.keyenv/bin/keyenv" ]; then
curl -fsSL https://keyenv.dev/install.sh | bash
fi
- export PATH="$HOME/.keyenv/bin:$PATH"
before_script:
- |
case "$TRAVIS_BRANCH" in
main) KEYENV_ENV=production ;;
staging) KEYENV_ENV=staging ;;
*) KEYENV_ENV=development ;;
esac
echo "Using KeyEnv environment: $KEYENV_ENV"
script:
- keyenv run -p $KEYENV_PROJECT -e $KEYENV_ENV -- npm ci
- keyenv run -p $KEYENV_PROJECT -e $KEYENV_ENV -- npm test
- keyenv run -p $KEYENV_PROJECT -e $KEYENV_ENV -- npm run build
deploy:
provider: script
script: keyenv run -p $KEYENV_PROJECT -e production -- npm run deploy
on:
branch: main
skip_cleanup: true
```
### Troubleshooting
#### Token Not Found
Ensure the variable is set in Travis CI settings and is accessible:
```yaml
script:
- echo "Token set: $([ -n "$KEYENV_TOKEN" ] && echo 'yes' || echo 'no')"
```
#### CLI Installation Fails
Try an alternative installation method:
```yaml
before_install:
- npm install -g @keyenv/cli
```
#### Secrets Not Loading
Verify the project and environment exist:
```yaml
script:
- keyenv whoami
- keyenv projects list
```
## Vercel Integration
Sync KeyEnv secrets to Vercel projects automatically.
Source: https://keyenv.dev/docs/guides/vercel/
This guide shows how to use KeyEnv secrets with Vercel deployments. You can either sync secrets directly to Vercel or pull them at build time.
### Overview
KeyEnv offers two ways to integrate with Vercel:
| Method | Best For | How It Works |
|--------|----------|--------------|
| **Native Sync** | Production apps | Auto-push secrets to Vercel environment variables |
| **Build-Time Pull** | Full control | Pull secrets during Vercel build process |
---
### Native Vercel Sync
Automatically sync secrets from KeyEnv to your Vercel project. When you update a secret in KeyEnv, it's pushed to Vercel immediately.
#### How It Works
1. Connect your Vercel account via OAuth
2. Map KeyEnv environments to Vercel projects/environments
3. Secrets sync automatically when changed
4. Optionally trigger a redeploy on update
#### Setup
##### 1. Connect Vercel Account
1. Go to **Settings** > **Integrations** in your KeyEnv dashboard
2. Click **Connect Vercel**
3. Authorize KeyEnv to access your Vercel account
4. Select the Vercel team (if applicable)
##### 2. Link Projects
1. In your KeyEnv project, go to **Settings** > **Vercel Sync**
2. Select your Vercel project from the dropdown
3. Map environments:
| KeyEnv Environment | Vercel Environment |
|--------------------|-------------------|
| `production` | Production |
| `staging` | Preview |
| `development` | Development |
4. Click **Enable Sync**
##### 3. Initial Sync
Click **Sync Now** to push all current secrets to Vercel. Future changes sync automatically.
#### Environment Mapping
KeyEnv environments map to Vercel's three environment types:
- **Production** - Live deployment on your main domain
- **Preview** - Branch/PR deployments
- **Development** - Local development via `vercel dev`
You can map multiple KeyEnv environments to a single Vercel environment, or vice versa.
#### Auto-Redeploy
Enable **Auto-Redeploy** to trigger a new deployment when secrets change:
1. Go to your KeyEnv project > **Settings** > **Vercel Sync**
2. Toggle **Redeploy on Change**
3. Select which Vercel environments to redeploy
> **Note**
>
> Auto-redeploy uses Vercel's Deploy Hooks. A new production deployment is triggered within 30 seconds of a secret change.
#### Sync Status
View sync status in the KeyEnv dashboard:
- **Synced** - All secrets match Vercel
- **Pending** - Changes waiting to sync
- **Error** - Sync failed (check logs)
---
### Build-Time Injection
Pull secrets from KeyEnv during your Vercel build. This gives you full control over when secrets are fetched.
#### Prerequisites
1. A KeyEnv project with secrets configured
2. A service token with access to production environment
#### Setup
##### 1. Create a Service Token
1. Go to **Project Settings** > **Service Tokens**
2. Click **Create Token**
3. Name it "Vercel Production"
4. Select the `production` environment
5. Copy the token
##### 2. Add Token to Vercel
1. Go to your Vercel project settings
2. Navigate to **Environment Variables**
3. Add a new variable:
- Name: `KEYENV_TOKEN`
- Value: Your service token
- Environments: Production (and Preview if needed)
##### 3. Update Build Command
In your `vercel.json`, modify the build command:
```json
{
"buildCommand": "curl -fsSL https://keyenv.dev/install.sh | bash && export PATH=\"$HOME/.keyenv/bin:$PATH\" && keyenv pull -e production && npm run build"
}
```
Or in `package.json`:
```json
{
"scripts": {
"vercel-build": "curl -fsSL https://keyenv.dev/install.sh | bash && export PATH=\"$HOME/.keyenv/bin:$PATH\" && keyenv pull -e production && npm run build"
}
}
```
#### Environment-Specific Builds
Use different environments for preview and production deployments.
##### Using VERCEL_ENV
Vercel sets `VERCEL_ENV` to `production`, `preview`, or `development` automatically:
```json
{
"scripts": {
"vercel-build": "curl -fsSL https://keyenv.dev/install.sh | bash && export PATH=\"$HOME/.keyenv/bin:$PATH\" && keyenv pull -e $VERCEL_ENV && npm run build"
}
}
```
##### Using Separate Tokens
For stricter security, create separate service tokens for each environment:
1. In Vercel, add environment variables:
- `KEYENV_TOKEN_PRODUCTION` - Token scoped to production
- `KEYENV_TOKEN_PREVIEW` - Token scoped to staging
2. Create a build script (`scripts/build.sh`):
```bash
#!/bin/bash
set -e
# Install KeyEnv CLI
curl -fsSL https://keyenv.dev/install.sh | bash
export PATH="$HOME/.keyenv/bin:$PATH"
# Select token and environment based on Vercel deployment type
if [ "$VERCEL_ENV" = "production" ]; then
export KEYENV_TOKEN="$KEYENV_TOKEN_PRODUCTION"
keyenv pull -e production
else
export KEYENV_TOKEN="$KEYENV_TOKEN_PREVIEW"
keyenv pull -e staging
fi
# Run the build
npm run build
```
3. Update `package.json`:
```json
{
"scripts": {
"vercel-build": "bash scripts/build.sh"
}
}
```
---
### Next.js Configuration
For Next.js projects, ensure your secrets are available at build time and runtime.
#### Server Components (App Router)
Secrets in `.env` are automatically available in server components:
```typescript
// app/api/route.ts
export async function GET() {
const apiKey = process.env.API_KEY;
// Use your secret
return Response.json({ status: 'ok' });
}
```
#### Server Actions
```typescript
// app/actions.ts
'use server';
export async function submitForm(data: FormData) {
const apiKey = process.env.API_KEY;
// Server action has access to secrets
}
```
#### Client-Side Variables
Prefix with `NEXT_PUBLIC_` for client-side access:
```bash
# In KeyEnv, name your secret:
NEXT_PUBLIC_ANALYTICS_ID=UA-123456789
NEXT_PUBLIC_API_URL=https://api.example.com
```
Then use in client components:
```typescript
// components/Analytics.tsx
'use client';
export function Analytics() {
const analyticsId = process.env.NEXT_PUBLIC_ANALYTICS_ID;
// Available in client bundle
}
```
> **Warning**
>
> Only use `NEXT_PUBLIC_` for non-sensitive values. These are embedded in the client bundle and visible to users.
---
### API Reference
KeyEnv uses the Vercel API to manage environment variables when using Native Sync.
#### Create/Update Variable
```
POST https://api.vercel.com/v10/projects/{projectId}/env
```
```json
{
"key": "DATABASE_URL",
"value": "postgres://user:pass@host:5432/db",
"type": "encrypted",
"target": ["production"]
}
```
#### Targets
| Target | Description |
|--------|-------------|
| `production` | Production deployments |
| `preview` | Preview deployments (PRs, branches) |
| `development` | Development environment (`vercel dev`) |
---
### Comparison: Native Sync vs Build-Time
| Feature | Native Sync | Build-Time Pull |
|---------|-------------|-----------------|
| Automatic updates | Yes | No (requires redeploy) |
| Setup complexity | Simple | Moderate |
| Runtime secrets | Yes | Build-time only |
| Audit trail | KeyEnv + Vercel | KeyEnv only |
| Offline builds | No | Yes (if cached) |
**Recommendation:** Use Native Sync for production applications. Use Build-Time Pull when you need more control or have specific requirements.
---
### Troubleshooting
#### Build fails with "keyenv: command not found"
Ensure the PATH is updated after installation:
```bash
export PATH="$HOME/.keyenv/bin:$PATH"
```
#### Secrets not available at runtime
If using serverless functions, secrets must be in Vercel's environment variables for runtime access. Build-time secrets are only available during the build.
For runtime access, use Native Sync or sync secrets manually to Vercel.
#### Sync fails with "Unauthorized"
1. Reconnect your Vercel account in KeyEnv Settings
2. Ensure the Vercel token hasn't expired
3. Check that KeyEnv has access to the target project
#### Different secrets per branch
Use Vercel's environment variable scoping:
1. Create branch-specific environments in KeyEnv
2. Map them to Vercel's Preview environment
3. Secrets are automatically scoped to the correct branches
---
### Best Practices
1. **Use Native Sync for simplicity** - Reduces build complexity and ensures runtime access
2. **Use service tokens** - Never use personal credentials in CI/CD
3. **Scope tokens narrowly** - Production token should only access production
4. **Don't log secrets** - Avoid `echo $SECRET` in build scripts
5. **Enable auto-redeploy** - Keep deployments in sync with secret changes
6. **Use environment mapping** - Match KeyEnv environments to Vercel environments
---
### Complete Example
Here's a complete setup for a Next.js application using build-time injection.
#### Project Structure
```
my-app/
├── .env.example # Template (committed)
├── .gitignore # Includes .env*
├── scripts/
│ └── build.sh # Build script
├── next.config.js
├── package.json
└── vercel.json
```
#### .gitignore
```
# Environment files
.env
.env.local
.env.production
.env.staging
```
#### .env.example
```bash
# Database
DATABASE_URL=postgres://user:password@localhost:5432/myapp
# API Keys
API_KEY=your-api-key-here
# Public (client-side)
NEXT_PUBLIC_APP_URL=https://myapp.com
NEXT_PUBLIC_ANALYTICS_ID=UA-123456789
```
#### package.json
```json
{
"name": "my-app",
"scripts": {
"dev": "next dev",
"build": "next build",
"vercel-build": "bash scripts/build.sh"
}
}
```
#### scripts/build.sh
```bash
#!/bin/bash
set -e
# Install KeyEnv CLI
curl -fsSL https://keyenv.dev/install.sh | bash
export PATH="$HOME/.keyenv/bin:$PATH"
# Pull secrets for the current environment
if [ "$VERCEL_ENV" = "production" ]; then
keyenv pull -e production
elif [ "$VERCEL_ENV" = "preview" ]; then
keyenv pull -e staging
else
keyenv pull -e development
fi
# Build the application
npm run build
```
#### Vercel Environment Variables
Add these in your Vercel project settings:
| Variable | Value | Environment |
|----------|-------|-------------|
| `KEYENV_TOKEN` | `srv_your_token_here` | Production, Preview |
#### KeyEnv Environments
Create environments in KeyEnv:
| Environment | Secrets |
|-------------|---------|
| `development` | Local development values |
| `staging` | Preview deployment values |
| `production` | Production values |
#### Deploy
1. Push to GitHub
2. Vercel automatically builds using `vercel-build` script
3. Secrets are pulled from KeyEnv during build
4. Application deploys with correct secrets
## Railway Integration
Deploy to Railway with KeyEnv secrets auto-sync.
Source: https://keyenv.dev/docs/guides/railway/
This guide shows how to use KeyEnv secrets with Railway deployments through automatic syncing via the Railway GraphQL API.
### Overview
There are two ways to use KeyEnv with Railway:
| Method | Best For | How It Works |
|--------|----------|--------------|
| **Auto-sync** | Production apps | Push secrets to Railway when they change |
| **Build-time injection** | Full control | Pull secrets during Railway build |
### Prerequisites
1. A KeyEnv project with secrets configured
2. A Railway project with services
3. A Railway API token
---
### Getting Your Railway API Token
1. Go to [Railway Dashboard](https://railway.app/account/tokens)
2. Click **Create Token**
3. Name it (e.g., "KeyEnv Integration")
4. Copy the token
### Getting Railway Project and Environment IDs
You'll need your Railway Project ID and Environment ID for the integration.
#### Using Railway CLI
```bash
# Install Railway CLI
npm install -g @railway/cli
# Login and link project
railway login
railway link
# Get project info
railway whoami
```
#### Using Railway Dashboard
1. Open your Railway project
2. The Project ID is in the URL: `railway.app/project/YOUR_PROJECT_ID`
3. Click on an environment to get its ID from the URL
#### Using GraphQL API
```bash
curl -X POST https://backboard.railway.app/graphql/v2 \
-H "Authorization: Bearer $RAILWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "query { me { projects { edges { node { id name environments { edges { node { id name } } } } } } } }"}'
```
---
### Option 1: Auto-Sync (Recommended)
Automatically sync secrets from KeyEnv to Railway when they change.
#### Manual Sync Script
Create a script to sync secrets from KeyEnv to Railway:
```bash
#!/bin/bash
# sync-to-railway.sh
set -e
# Configuration - replace with your values
KEYENV_TOKEN="${KEYENV_TOKEN}"
RAILWAY_TOKEN="${RAILWAY_TOKEN}"
RAILWAY_PROJECT_ID="${RAILWAY_PROJECT_ID:-YOUR_RAILWAY_PROJECT_ID}"
RAILWAY_ENV_ID="${RAILWAY_ENV_ID:-YOUR_RAILWAY_ENVIRONMENT_ID}"
KEYENV_PROJECT_ID="${KEYENV_PROJECT_ID:-YOUR_KEYENV_PROJECT_ID}"
KEYENV_ENV="${KEYENV_ENV:-production}"
# Fetch secrets from KeyEnv
echo "Fetching secrets from KeyEnv..."
secrets=$(curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"https://api.keyenv.dev/api/v1/projects/$KEYENV_PROJECT_ID/environments/$KEYENV_ENV/secrets/export")
# Sync each secret to Railway
echo "$secrets" | jq -c '.secrets[]' | while read -r secret; do
key=$(echo "$secret" | jq -r '.key')
value=$(echo "$secret" | jq -r '.value')
# Upsert variable to Railway
curl -sf -X POST https://backboard.railway.app/graphql/v2 \
-H "Authorization: Bearer $RAILWAY_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"query\": \"mutation { variableUpsert(input: { projectId: \\\"$RAILWAY_PROJECT_ID\\\", environmentId: \\\"$RAILWAY_ENV_ID\\\", name: \\\"$key\\\", value: \\\"$value\\\" }) { id } }\"
}" > /dev/null
echo "Synced: $key"
done
echo "Sync complete!"
```
Make it executable and run:
```bash
chmod +x sync-to-railway.sh
# Set environment variables
export KEYENV_TOKEN="srv_your_keyenv_token"
export RAILWAY_TOKEN="your_railway_token"
export RAILWAY_PROJECT_ID="your-railway-project-id"
export RAILWAY_ENV_ID="your-railway-environment-id"
export KEYENV_PROJECT_ID="your-keyenv-project-id"
# Run the sync
./sync-to-railway.sh
```
#### GitHub Actions Workflow
Automatically sync on push to main:
```yaml
# .github/workflows/sync-secrets.yml
name: Sync Secrets to Railway
on:
push:
branches: [main]
workflow_dispatch:
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Sync KeyEnv to Railway
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
RAILWAY_PROJECT_ID: ${{ vars.RAILWAY_PROJECT_ID }}
RAILWAY_ENV_ID: ${{ vars.RAILWAY_ENV_ID }}
KEYENV_PROJECT_ID: ${{ vars.KEYENV_PROJECT_ID }}
KEYENV_ENV: production
run: |
# Fetch secrets from KeyEnv
secrets=$(curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"https://api.keyenv.dev/api/v1/projects/$KEYENV_PROJECT_ID/environments/$KEYENV_ENV/secrets/export")
# Sync each secret to Railway
echo "$secrets" | jq -c '.secrets[]' | while read -r secret; do
key=$(echo "$secret" | jq -r '.key')
value=$(echo "$secret" | jq -r '.value')
curl -sf -X POST https://backboard.railway.app/graphql/v2 \
-H "Authorization: Bearer $RAILWAY_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"query\": \"mutation { variableUpsert(input: { projectId: \\\"$RAILWAY_PROJECT_ID\\\", environmentId: \\\"$RAILWAY_ENV_ID\\\", name: \\\"$key\\\", value: \\\"$value\\\" }) { id } }\"
}" > /dev/null
echo "Synced: $key"
done
```
#### GitLab CI Workflow
```yaml
# .gitlab-ci.yml
sync_secrets:
stage: deploy
image: alpine:latest
variables:
KEYENV_TOKEN: $KEYENV_TOKEN
RAILWAY_TOKEN: $RAILWAY_TOKEN
RAILWAY_PROJECT_ID: "YOUR_RAILWAY_PROJECT_ID"
RAILWAY_ENV_ID: "YOUR_RAILWAY_ENVIRONMENT_ID"
KEYENV_PROJECT_ID: "YOUR_KEYENV_PROJECT_ID"
KEYENV_ENV: "production"
before_script:
- apk add --no-cache curl jq
script:
- |
secrets=$(curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"https://api.keyenv.dev/api/v1/projects/$KEYENV_PROJECT_ID/environments/$KEYENV_ENV/secrets/export")
echo "$secrets" | jq -c '.secrets[]' | while read -r secret; do
key=$(echo "$secret" | jq -r '.key')
value=$(echo "$secret" | jq -r '.value')
curl -sf -X POST https://backboard.railway.app/graphql/v2 \
-H "Authorization: Bearer $RAILWAY_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"query\": \"mutation { variableUpsert(input: { projectId: \\\"$RAILWAY_PROJECT_ID\\\", environmentId: \\\"$RAILWAY_ENV_ID\\\", name: \\\"$key\\\", value: \\\"$value\\\" }) { id } }\"
}" > /dev/null
echo "Synced: $key"
done
only:
- main
```
---
### Option 2: Build-Time Injection
Pull secrets from KeyEnv during your Railway build.
#### Using Nixpacks (Default Builder)
Create a `nixpacks.toml` file in your project root:
```toml
# nixpacks.toml
[phases.setup]
cmds = [
"curl -fsSL https://keyenv.dev/install.sh | bash",
"export PATH=\"$HOME/.keyenv/bin:$PATH\"",
"keyenv pull -e production"
]
```
#### Using Build Command
In Railway service settings, set a custom build command:
```bash
curl -fsSL https://keyenv.dev/install.sh | bash && export PATH="$HOME/.keyenv/bin:$PATH" && keyenv pull -e production && npm run build
```
#### Using Dockerfile
```dockerfile
# Dockerfile
FROM node:20-alpine
# Install dependencies for KeyEnv
RUN apk add --no-cache curl bash
# Install KeyEnv CLI
RUN curl -fsSL https://keyenv.dev/install.sh | bash
ENV PATH="/root/.keyenv/bin:$PATH"
WORKDIR /app
COPY package*.json ./
RUN npm ci
# Pull secrets at build time
ARG KEYENV_TOKEN
ENV KEYENV_TOKEN=$KEYENV_TOKEN
RUN keyenv pull -e production
COPY . .
RUN npm run build
CMD ["npm", "start"]
```
In Railway, add the build argument:
1. Go to **Service Settings** > **Build**
2. Add Build Argument: `KEYENV_TOKEN`
3. Set the value to your KeyEnv service token
---
### SDK Integration
#### Node.js
Use the KeyEnv SDK for runtime secret loading:
```typescript
// src/config.ts
import { KeyEnv } from '@keyenv/node';
const client = new KeyEnv({
token: process.env.KEYENV_TOKEN!,
});
// Load secrets at startup
await client.loadEnv('YOUR_PROJECT_ID', 'production');
// Now use your secrets
console.log(process.env.DATABASE_URL);
```
#### Python
```python
# config.py
import os
from keyenv import KeyEnv
client = KeyEnv(token=os.environ['KEYENV_TOKEN'])
# Load secrets at startup
client.load_env('YOUR_PROJECT_ID', 'production')
# Now use your secrets
print(os.environ['DATABASE_URL'])
```
---
### Environment Mapping
Map KeyEnv environments to Railway environments:
| KeyEnv Environment | Railway Environment |
|--------------------|---------------------|
| `development` | Development |
| `staging` | Staging |
| `production` | Production |
Use different tokens and environment IDs for each mapping.
---
### Railway GraphQL API Reference
#### Upsert a Variable
```graphql
mutation {
variableUpsert(input: {
projectId: "YOUR_PROJECT_ID",
environmentId: "YOUR_ENVIRONMENT_ID",
name: "DATABASE_URL",
value: "postgres://user:pass@host:5432/db"
}) {
id
}
}
```
#### Delete a Variable
```graphql
mutation {
variableDelete(input: {
projectId: "YOUR_PROJECT_ID",
environmentId: "YOUR_ENVIRONMENT_ID",
name: "OLD_SECRET"
})
}
```
#### List All Variables
```graphql
query {
variables(
projectId: "YOUR_PROJECT_ID",
environmentId: "YOUR_ENVIRONMENT_ID"
)
}
```
#### curl Example
```bash
# Upsert a variable
curl -X POST https://backboard.railway.app/graphql/v2 \
-H "Authorization: Bearer $RAILWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { variableUpsert(input: { projectId: \"YOUR_PROJECT_ID\", environmentId: \"YOUR_ENVIRONMENT_ID\", name: \"DATABASE_URL\", value: \"postgres://...\" }) { id } }"
}'
```
---
### Troubleshooting
#### "Unauthorized" error from Railway
1. Check that your Railway token is valid
2. Ensure the token has access to the project
3. Verify the Project ID and Environment ID are correct
#### Secrets not available at runtime
Railway caches environment variables. After syncing:
1. Trigger a new deployment, or
2. Use the Railway CLI: `railway redeploy`
#### GraphQL query fails
Ensure you're using the correct API endpoint:
- **GraphQL v2:** `https://backboard.railway.app/graphql/v2`
#### Rate limiting
Railway's API has rate limits. For large numbers of secrets, add delays between requests:
```bash
# Add between API calls
sleep 0.5
```
#### Sync script fails silently
Add error handling to your sync script:
```bash
#!/bin/bash
set -e # Exit on error
# Add -f flag to curl to fail on HTTP errors
secrets=$(curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"https://api.keyenv.dev/api/v1/projects/$KEYENV_PROJECT_ID/environments/$KEYENV_ENV/secrets/export") || {
echo "Failed to fetch secrets from KeyEnv"
exit 1
}
```
---
### Best Practices
1. **Use service tokens** - Never use personal credentials in CI/CD
2. **Scope tokens narrowly** - Production token should only access production
3. **Sync on deploy** - Trigger sync as part of your deployment pipeline
4. **Use environment mapping** - Map KeyEnv environments to Railway environments consistently
5. **Monitor sync status** - Log sync operations for debugging
6. **Rotate tokens periodically** - Update Railway and KeyEnv tokens regularly
---
### Security Considerations
> **Warning**
>
> Store your Railway API token securely. Never commit tokens to version control.
- Use GitHub Secrets or Railway's secret management for tokens
- Rotate tokens periodically
- Use separate tokens for different environments
- Audit token usage regularly
---
### Complete Example
Here's a complete setup for a Node.js application with GitHub Actions sync.
#### Project Structure
```
my-railway-app/
├── .github/
│ └── workflows/
│ └── sync-secrets.yml
├── scripts/
│ └── sync-to-railway.sh
├── src/
│ └── index.ts
├── package.json
└── Dockerfile
```
#### .github/workflows/sync-secrets.yml
```yaml
name: Sync Secrets to Railway
on:
push:
branches: [main]
workflow_dispatch:
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Sync KeyEnv to Railway
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
RAILWAY_PROJECT_ID: ${{ vars.RAILWAY_PROJECT_ID }}
RAILWAY_ENV_ID: ${{ vars.RAILWAY_ENV_ID }}
KEYENV_PROJECT_ID: ${{ vars.KEYENV_PROJECT_ID }}
KEYENV_ENV: production
run: |
secrets=$(curl -sf -H "Authorization: Bearer $KEYENV_TOKEN" \
"https://api.keyenv.dev/api/v1/projects/$KEYENV_PROJECT_ID/environments/$KEYENV_ENV/secrets/export")
echo "$secrets" | jq -c '.secrets[]' | while read -r secret; do
key=$(echo "$secret" | jq -r '.key')
value=$(echo "$secret" | jq -r '.value')
curl -sf -X POST https://backboard.railway.app/graphql/v2 \
-H "Authorization: Bearer $RAILWAY_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"query\": \"mutation { variableUpsert(input: { projectId: \\\"$RAILWAY_PROJECT_ID\\\", environmentId: \\\"$RAILWAY_ENV_ID\\\", name: \\\"$key\\\", value: \\\"$value\\\" }) { id } }\"
}" > /dev/null
echo "Synced: $key"
done
```
#### GitHub Repository Settings
Add these secrets and variables:
**Secrets:**
| Name | Value |
|------|-------|
| `KEYENV_TOKEN` | `srv_your_keyenv_token` |
| `RAILWAY_TOKEN` | `your_railway_api_token` |
**Variables:**
| Name | Value |
|------|-------|
| `RAILWAY_PROJECT_ID` | `your-railway-project-id` |
| `RAILWAY_ENV_ID` | `your-railway-environment-id` |
| `KEYENV_PROJECT_ID` | `your-keyenv-project-id` |
#### KeyEnv Environments
Create environments in KeyEnv:
| Environment | Secrets |
|-------------|---------|
| `development` | Local development values |
| `staging` | Preview deployment values |
| `production` | Production values |
#### Deploy Flow
1. Update secrets in KeyEnv dashboard
2. Push to `main` branch (or manually trigger workflow)
3. GitHub Actions syncs secrets to Railway
4. Railway redeploys with new secrets
---
### Coming Soon
We're building a native Railway integration that will:
- Connect via OAuth (no API tokens needed)
- Automatically sync on secret changes
- Provide a dashboard to manage environment mappings
- Support webhooks for real-time sync
Join our waitlist for early access.
## Render
Sync KeyEnv secrets to Render services.
Source: https://keyenv.dev/docs/guides/render/
Sync secrets from KeyEnv to your Render services.
### Prerequisites
- Render account with a deployed service
- [Render API key](https://render.com/docs/api#getting-started)
- KeyEnv service token with read access
### Integration Scripts
The [`integrations/render/`](https://github.com/keyenv/keyenv/tree/main/integrations/render)
directory contains ready-to-use sync scripts in Bash, TypeScript, and Python.
These scripts use the Render API directly (no KeyEnv CLI required):
```bash
# Clone or copy from the repo
cd integrations/render
export KEYENV_TOKEN=your-keyenv-token
export RENDER_API_KEY=your-render-api-key
export RENDER_SERVICE_ID=srv-xxxxxxxxxxxxx
./sync-to-render.sh # Bash
npx ts-node sync-to-render.ts # TypeScript
python3 sync-to-render.py # Python
```
By default the scripts merge KeyEnv secrets with existing Render env vars
(KeyEnv takes precedence). Set `REPLACE_ALL=true` to replace all Render vars.
### Quick Sync
For a one-off sync using the KeyEnv CLI:
```bash
#!/bin/bash
set -euo pipefail
export KEYENV_TOKEN=your-keyenv-token
export RENDER_API_KEY=your-render-api-key
RENDER_SERVICE_ID=srv-xxxxxxxxxxxxx
# Export and sync
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format json)
echo "$secrets" | jq '[.secrets[] | {key: .key, value: .value}]' | \
curl -s -X PUT "https://api.render.com/v1/services/$RENDER_SERVICE_ID/env-vars" \
-H "Authorization: Bearer $RENDER_API_KEY" \
-H "Content-Type: application/json" \
-d @-
echo "Secrets synced to Render!"
```
### Find Your Service ID
1. Go to your Render Dashboard
2. Click on your service
3. The Service ID is in the URL: `dashboard.render.com/web/srv-xxxxxxxxxxxxx`
Or use the API:
```bash
curl -s "https://api.render.com/v1/services" \
-H "Authorization: Bearer $RENDER_API_KEY" | \
jq '.[] | {name: .service.name, id: .service.id}'
```
### Sync Script
Create a reusable sync script:
```bash
#!/bin/bash
# sync-to-render.sh
set -euo pipefail
: "${KEYENV_TOKEN:?KEYENV_TOKEN is required}"
: "${RENDER_API_KEY:?RENDER_API_KEY is required}"
PROJECT_ID="${KEYENV_PROJECT:-YOUR_PROJECT_ID}"
ENVIRONMENT="${KEYENV_ENV:-production}"
SERVICE_ID="${RENDER_SERVICE_ID:-srv-xxxxxxxxxxxxx}"
echo "Syncing KeyEnv ($ENVIRONMENT) to Render ($SERVICE_ID)..."
# Export secrets from KeyEnv
secrets=$(keyenv export -p "$PROJECT_ID" -e "$ENVIRONMENT" --format json)
# Transform and sync to Render
echo "$secrets" | jq '[.secrets[] | {key: .key, value: .value}]' | \
curl -s -X PUT "https://api.render.com/v1/services/$SERVICE_ID/env-vars" \
-H "Authorization: Bearer $RENDER_API_KEY" \
-H "Content-Type: application/json" \
-d @-
echo "Done! Render will automatically redeploy."
```
### CI/CD Integration
#### GitHub Actions
```yaml
name: Deploy to Render
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install KeyEnv CLI
run: curl -fsSL https://keyenv.dev/install.sh | bash
- name: Sync secrets to Render
run: |
export PATH="$HOME/.keyenv/bin:$PATH"
secrets=$(keyenv export -p ${{ vars.KEYENV_PROJECT }} -e production --format json)
echo "$secrets" | jq '[.secrets[] | {key: .key, value: .value}]' | \
curl -s -X PUT "https://api.render.com/v1/services/${{ vars.RENDER_SERVICE_ID }}/env-vars" \
-H "Authorization: Bearer ${{ secrets.RENDER_API_KEY }}" \
-H "Content-Type: application/json" \
-d @-
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
- name: Trigger deploy
run: |
curl -X POST "https://api.render.com/v1/services/${{ vars.RENDER_SERVICE_ID }}/deploys" \
-H "Authorization: Bearer ${{ secrets.RENDER_API_KEY }}"
```
### Multiple Services
Sync to multiple Render services:
```bash
#!/bin/bash
# sync-all-services.sh
declare -A SERVICES=(
["web"]="srv-web123"
["api"]="srv-api456"
["worker"]="srv-worker789"
)
for name in "${!SERVICES[@]}"; do
service_id="${SERVICES[$name]}"
echo "Syncing to $name ($service_id)..."
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format json)
echo "$secrets" | jq '[.secrets[] | {key: .key, value: .value}]' | \
curl -s -X PUT "https://api.render.com/v1/services/$service_id/env-vars" \
-H "Authorization: Bearer $RENDER_API_KEY" \
-H "Content-Type: application/json" \
-d @-
done
```
### Environment Groups
Render supports environment groups for sharing secrets across services. Sync to a group:
```bash
# Get environment group ID
curl -s "https://api.render.com/v1/env-groups" \
-H "Authorization: Bearer $RENDER_API_KEY" | jq '.'
# Sync to environment group
ENV_GROUP_ID="evg-xxxxxxxxxxxxx"
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format json)
echo "$secrets" | jq '[.secrets[] | {key: .key, value: .value}]' | \
curl -s -X PUT "https://api.render.com/v1/env-groups/$ENV_GROUP_ID/env-vars" \
-H "Authorization: Bearer $RENDER_API_KEY" \
-H "Content-Type: application/json" \
-d @-
```
### Selective Sync
Sync only specific secrets:
```bash
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format json)
# Only sync secrets starting with "DB_" or "API_"
echo "$secrets" | \
jq '[.secrets[] | select(.key | test("^(DB_|API_)")) | {key: .key, value: .value}]' | \
curl -s -X PUT "https://api.render.com/v1/services/$SERVICE_ID/env-vars" \
-H "Authorization: Bearer $RENDER_API_KEY" \
-H "Content-Type: application/json" \
-d @-
```
### Verify Sync
Check current environment variables:
```bash
curl -s "https://api.render.com/v1/services/$SERVICE_ID/env-vars" \
-H "Authorization: Bearer $RENDER_API_KEY" | \
jq '.[] | {key: .envVar.key}'
```
### render.yaml Configuration
For Blueprint-based deployments, non-sensitive config goes in `render.yaml`:
```yaml
services:
- type: web
name: myapp
env: node
buildCommand: npm install && npm run build
startCommand: npm start
envVars:
- key: NODE_ENV
value: production
- key: LOG_LEVEL
value: info
# Sensitive values synced from KeyEnv via API
```
### Best Practices
1. **Use environment groups** - Share common secrets across services
2. **Automate syncing** - Run sync in CI/CD before deployments
3. **Don't mix methods** - Either use render.yaml OR API sync, not both for the same keys
4. **Version control non-secrets** - Put non-sensitive config in render.yaml
### Troubleshooting
#### API Rate Limits
Render has API rate limits. If syncing many services:
```bash
for service_id in "${SERVICE_IDS[@]}"; do
# ... sync ...
sleep 1 # Add delay between requests
done
```
#### Service Not Redeploying
Trigger a manual deploy after syncing:
```bash
curl -X POST "https://api.render.com/v1/services/$SERVICE_ID/deploys" \
-H "Authorization: Bearer $RENDER_API_KEY"
```
#### Permission Errors
Verify your API key has the right permissions:
```bash
curl -s "https://api.render.com/v1/owners" \
-H "Authorization: Bearer $RENDER_API_KEY"
```
## Fly.io
Sync KeyEnv secrets to Fly.io applications.
Source: https://keyenv.dev/docs/guides/flyio/
Sync secrets from KeyEnv to your Fly.io applications.
### Prerequisites
- Fly.io account with an application deployed
- [flyctl](https://fly.io/docs/hands-on/install-flyctl/) CLI installed
- KeyEnv service token with read access
### Quick Sync
The simplest way to sync secrets:
```bash
export KEYENV_TOKEN=your-service-token
keyenv export -p YOUR_PROJECT_ID -e production --format shell | fly secrets import
```
This exports all secrets from KeyEnv and imports them directly into your Fly.io app.
### Sync Script
Create a reusable sync script:
```bash
#!/bin/bash
# sync-to-fly.sh
set -euo pipefail
PROJECT_ID="${KEYENV_PROJECT:-YOUR_PROJECT_ID}"
ENVIRONMENT="${KEYENV_ENV:-production}"
# Sync secrets
echo "Syncing secrets from KeyEnv ($ENVIRONMENT) to Fly.io..."
keyenv export -p "$PROJECT_ID" -e "$ENVIRONMENT" --format shell | fly secrets import
echo "Done! Fly.io will automatically redeploy."
```
Run it:
```bash
chmod +x sync-to-fly.sh
KEYENV_TOKEN=xxx ./sync-to-fly.sh
```
### CI/CD Integration
#### GitHub Actions
```yaml
name: Deploy to Fly.io
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install KeyEnv CLI
run: curl -fsSL https://keyenv.dev/install.sh | bash
- name: Setup Fly.io
uses: superfly/flyctl-actions/setup-flyctl@master
- name: Sync secrets
run: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv export -p ${{ vars.KEYENV_PROJECT }} -e production --format shell | fly secrets import
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
- name: Deploy
run: fly deploy
env:
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
```
#### GitLab CI
```yaml
deploy:
stage: deploy
image: ubuntu:latest
before_script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://keyenv.dev/install.sh | bash
- curl -L https://fly.io/install.sh | sh
- export PATH="$HOME/.keyenv/bin:$HOME/.fly/bin:$PATH"
script:
- keyenv export -p $KEYENV_PROJECT -e production --format shell | fly secrets import
- fly deploy
only:
- main
```
### Selective Sync
Sync only specific secrets:
```bash
# Export all secrets
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format json)
# Filter and sync specific ones
echo "$secrets" | jq -r '.secrets[] | select(.key | startswith("FLY_")) | "\(.key)=\(.value)"' | fly secrets import
```
### Multi-App Deployment
Sync to multiple Fly.io apps:
```bash
#!/bin/bash
# sync-all-apps.sh
APPS=("app-web" "app-api" "app-worker")
ENVIRONMENTS=("production" "production" "production")
for i in "${!APPS[@]}"; do
echo "Syncing to ${APPS[$i]}..."
keyenv export -p YOUR_PROJECT_ID -e "${ENVIRONMENTS[$i]}" --format shell | \
fly secrets import -a "${APPS[$i]}"
done
```
### Environment-Based Sync
Sync different environments:
```bash
#!/bin/bash
# sync-env.sh
ENV=${1:-production}
APP=${2:-my-app}
case "$ENV" in
production)
APP_NAME="$APP"
;;
staging)
APP_NAME="$APP-staging"
;;
*)
echo "Unknown environment: $ENV"
exit 1
;;
esac
keyenv export -p YOUR_PROJECT_ID -e "$ENV" --format shell | fly secrets import -a "$APP_NAME"
```
### Verify Secrets
Check what secrets are currently set:
```bash
# List Fly.io secrets
fly secrets list
# Compare with KeyEnv
keyenv list -p YOUR_PROJECT_ID -e production
```
### Remove Secrets
Remove a secret from Fly.io:
```bash
fly secrets unset SECRET_NAME
```
Remove all secrets and re-sync:
```bash
# Get current secret names
fly secrets list | tail -n +2 | awk '{print $1}' | xargs fly secrets unset
# Re-sync from KeyEnv
keyenv export -p YOUR_PROJECT_ID -e production --format shell | fly secrets import
```
### fly.toml Configuration
While secrets are managed via `fly secrets`, you can set non-sensitive config in `fly.toml`:
```toml
[env]
LOG_LEVEL = "info"
NODE_ENV = "production"
# Sensitive values come from fly secrets (synced from KeyEnv)
# DATABASE_URL, API_KEY, etc.
```
### Best Practices
1. **Automate in CI/CD** - Don't manually sync secrets
2. **Use separate environments** - Don't mix production and staging secrets
3. **Audit changes** - Fly.io tracks secret changes in activity logs
4. **Don't commit tokens** - Use CI/CD secrets for KEYENV_TOKEN and FLY_API_TOKEN
### Troubleshooting
#### Secrets Not Updating
Fly.io redeploys automatically when secrets change. Check the deployment:
```bash
fly status
fly logs
```
#### Format Issues
Ensure the export format is correct:
```bash
# Debug the export
keyenv export -p YOUR_PROJECT_ID -e production --format shell
# Should output:
# KEY1=value1
# KEY2=value2
```
#### Permission Denied
Verify your Fly.io token:
```bash
fly auth whoami
```
And your KeyEnv token:
```bash
keyenv whoami
```
## Cloudflare Workers
Sync KeyEnv secrets to Cloudflare Workers.
Source: https://keyenv.dev/docs/guides/cloudflare-workers/
Sync secrets from KeyEnv to your Cloudflare Workers.
### Prerequisites
- Cloudflare account with Workers enabled
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) installed
- KeyEnv service token with read access
### Quick Sync
```bash
export KEYENV_TOKEN=your-service-token
# Export and bulk upload secrets
keyenv export -p YOUR_PROJECT_ID -e production --format json | \
jq '[.secrets[] | {name: .key, text: .value, type: "secret_text"}]' | \
wrangler secret:bulk
```
### Sync Script
Create a reusable sync script:
```bash
#!/bin/bash
# sync-to-cloudflare.sh
set -euo pipefail
: "${KEYENV_TOKEN:?KEYENV_TOKEN is required}"
PROJECT_ID="${KEYENV_PROJECT:-YOUR_PROJECT_ID}"
ENVIRONMENT="${KEYENV_ENV:-production}"
echo "Syncing KeyEnv ($ENVIRONMENT) to Cloudflare Workers..."
# Export and transform for Cloudflare
keyenv export -p "$PROJECT_ID" -e "$ENVIRONMENT" --format json | \
jq '[.secrets[] | {name: .key, text: .value, type: "secret_text"}]' | \
wrangler secret:bulk
echo "Secrets synced to Cloudflare Workers!"
```
### CI/CD Integration
#### GitHub Actions
```yaml
name: Deploy Worker
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install KeyEnv CLI
run: curl -fsSL https://keyenv.dev/install.sh | bash
- name: Sync secrets
run: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv export -p ${{ vars.KEYENV_PROJECT }} -e production --format json | \
jq '[.secrets[] | {name: .key, text: .value, type: "secret_text"}]' | \
npx wrangler secret:bulk
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
- name: Deploy Worker
run: npx wrangler deploy
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
```
### Single Secret Sync
Sync individual secrets:
```bash
# Get a specific secret
value=$(keyenv get -p YOUR_PROJECT_ID -e production DATABASE_URL)
# Set in Cloudflare
echo "$value" | wrangler secret put DATABASE_URL
```
### Multiple Workers
Sync to multiple Workers:
```bash
#!/bin/bash
WORKERS=("api-worker" "auth-worker" "queue-worker")
for worker in "${WORKERS[@]}"; do
echo "Syncing to $worker..."
keyenv export -p YOUR_PROJECT_ID -e production --format json | \
jq '[.secrets[] | {name: .key, text: .value, type: "secret_text"}]' | \
wrangler secret:bulk --name "$worker"
done
```
### Selective Sync
Sync only specific secrets:
```bash
# Only sync secrets that don't contain "LOCAL" in the key
keyenv export -p YOUR_PROJECT_ID -e production --format json | \
jq '[.secrets[] | select(.key | contains("LOCAL") | not) | {name: .key, text: .value, type: "secret_text"}]' | \
wrangler secret:bulk
```
### wrangler.toml Configuration
Non-sensitive config goes in `wrangler.toml`:
```toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"
[vars]
ENVIRONMENT = "production"
LOG_LEVEL = "info"
PUBLIC_API_URL = "https://api.example.com"
# Secrets are managed via wrangler secret (synced from KeyEnv)
# DATABASE_URL, API_KEY, etc.
```
### Using Secrets in Workers
Access secrets in your Worker code:
```typescript
// src/index.ts
export interface Env {
DATABASE_URL: string;
API_KEY: string;
ENVIRONMENT: string; // From wrangler.toml [vars]
}
export default {
async fetch(request: Request, env: Env): Promise {
// Access secrets
const dbUrl = env.DATABASE_URL;
const apiKey = env.API_KEY;
return new Response('OK');
},
};
```
### Durable Objects
Secrets are available to Durable Objects too:
```typescript
export class MyDurableObject {
constructor(private state: DurableObjectState, private env: Env) {}
async fetch(request: Request): Promise {
// Access secrets via this.env
const apiKey = this.env.API_KEY;
return new Response('OK');
}
}
```
### Workers KV
For frequently accessed secrets, consider caching in KV:
```typescript
async function getSecret(env: Env, key: string): Promise {
// Try KV cache first
let value = await env.SECRETS_KV.get(key);
if (!value) {
// Fall back to env binding
value = env[key as keyof Env] as string;
// Cache for 1 hour
await env.SECRETS_KV.put(key, value, { expirationTtl: 3600 });
}
return value;
}
```
### List Current Secrets
View secrets currently set in your Worker:
```bash
wrangler secret list
```
### Delete Secrets
Remove a secret:
```bash
wrangler secret delete SECRET_NAME
```
Remove all and re-sync:
```bash
# List and delete all
for secret in $(wrangler secret list | tail -n +3 | awk '{print $1}'); do
wrangler secret delete "$secret" --force
done
# Re-sync from KeyEnv
keyenv export -p YOUR_PROJECT_ID -e production --format json | \
jq '[.secrets[] | {name: .key, text: .value, type: "secret_text"}]' | \
wrangler secret:bulk
```
### Pages Functions
For Cloudflare Pages with Functions, set secrets via the dashboard or API:
```bash
# Using Pages API
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format json)
echo "$secrets" | jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/pages/projects/$PROJECT_NAME" \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"deployment_configs\":{\"production\":{\"env_vars\":{\"$key\":{\"value\":\"$value\",\"type\":\"secret_text\"}}}}}"
done
```
### Best Practices
1. **Use wrangler.toml for non-secrets** - Version control public config
2. **Automate syncing** - Run sync in CI/CD before deployments
3. **Use secret bindings** - Access via `env.SECRET_NAME`, not `process.env`
4. **Separate by environment** - Use different Workers for staging/production
### Troubleshooting
#### Wrangler Not Logged In
```bash
wrangler login
# or use API token
export CLOUDFLARE_API_TOKEN=your-token
```
#### Secret Not Available
Ensure you've deployed after adding secrets:
```bash
wrangler deploy
```
#### Type Errors
Update your `Env` interface to include all secrets:
```typescript
export interface Env {
// Add all your secrets here
DATABASE_URL: string;
API_KEY: string;
}
```
## Google Cloud Run
Sync KeyEnv secrets to Google Cloud Run services.
Source: https://keyenv.dev/docs/guides/google-cloud-run/
Sync secrets from KeyEnv to your Cloud Run services.
### Prerequisites
- Google Cloud project with Cloud Run enabled
- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
- KeyEnv service token with read access
### Quick Sync
Sync secrets directly as environment variables:
```bash
export KEYENV_TOKEN=your-service-token
SERVICE_NAME="my-service"
REGION="us-central1"
# Export and set env vars
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format shell)
gcloud run services update "$SERVICE_NAME" \
--region="$REGION" \
--update-env-vars="$secrets"
```
### Sync Script
Create a reusable sync script:
```bash
#!/bin/bash
# sync-to-cloud-run.sh
set -euo pipefail
: "${KEYENV_TOKEN:?KEYENV_TOKEN is required}"
PROJECT_ID="${KEYENV_PROJECT:-YOUR_PROJECT_ID}"
ENVIRONMENT="${KEYENV_ENV:-production}"
SERVICE_NAME="${CLOUD_RUN_SERVICE:-my-service}"
REGION="${CLOUD_RUN_REGION:-us-central1}"
echo "Syncing KeyEnv ($ENVIRONMENT) to Cloud Run ($SERVICE_NAME)..."
# Export secrets
secrets=$(keyenv export -p "$PROJECT_ID" -e "$ENVIRONMENT" --format shell)
# Update Cloud Run service
gcloud run services update "$SERVICE_NAME" \
--region="$REGION" \
--update-env-vars="$secrets"
echo "Done! Cloud Run is redeploying..."
```
### Using Secret Manager (Recommended)
For production, store secrets in Google Secret Manager and reference them in Cloud Run:
#### 1. Sync to Secret Manager
```bash
#!/bin/bash
# sync-to-secret-manager.sh
set -euo pipefail
GCP_PROJECT="your-gcp-project"
# Export secrets from KeyEnv
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format json)
# Create/update each secret in Secret Manager
echo "$secrets" | jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
# Try to create, or add new version if exists
if gcloud secrets describe "$key" --project="$GCP_PROJECT" &>/dev/null; then
echo -n "$value" | gcloud secrets versions add "$key" --data-file=- --project="$GCP_PROJECT"
echo "Updated: $key"
else
echo -n "$value" | gcloud secrets create "$key" --data-file=- --project="$GCP_PROJECT"
echo "Created: $key"
fi
done
```
#### 2. Reference in Cloud Run
```bash
gcloud run services update my-service \
--region=us-central1 \
--update-secrets="DATABASE_URL=DATABASE_URL:latest,API_KEY=API_KEY:latest"
```
Or in your `service.yaml`:
```yaml
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
name: my-service
spec:
template:
spec:
containers:
- image: gcr.io/my-project/my-service
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: DATABASE_URL
key: latest
- name: API_KEY
valueFrom:
secretKeyRef:
name: API_KEY
key: latest
```
### CI/CD Integration
#### GitHub Actions
```yaml
name: Deploy to Cloud Run
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v4
- name: Install KeyEnv CLI
run: curl -fsSL https://keyenv.dev/install.sh | bash
- name: Authenticate to Google Cloud
uses: google-github-actions/auth@v2
with:
workload_identity_provider: ${{ vars.WIF_PROVIDER }}
service_account: ${{ vars.WIF_SERVICE_ACCOUNT }}
- name: Set up Cloud SDK
uses: google-github-actions/setup-gcloud@v2
- name: Sync secrets to Secret Manager
run: |
export PATH="$HOME/.keyenv/bin:$PATH"
keyenv export -p ${{ vars.KEYENV_PROJECT }} -e production --format json | \
jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
if gcloud secrets describe "$key" &>/dev/null; then
echo -n "$value" | gcloud secrets versions add "$key" --data-file=-
else
echo -n "$value" | gcloud secrets create "$key" --data-file=-
fi
done
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
- name: Deploy to Cloud Run
uses: google-github-actions/deploy-cloudrun@v2
with:
service: my-service
region: us-central1
image: gcr.io/${{ vars.GCP_PROJECT }}/my-service
```
#### Cloud Build
```yaml
# cloudbuild.yaml
steps:
- name: 'gcr.io/cloud-builders/curl'
args: ['-fsSL', 'https://keyenv.dev/install.sh', '-o', 'install.sh']
- name: 'ubuntu'
entrypoint: 'bash'
args: ['install.sh']
- name: 'ubuntu'
entrypoint: 'bash'
args:
- '-c'
- |
export PATH="$$HOME/.keyenv/bin:$$PATH"
keyenv export -p $$KEYENV_PROJECT -e production --format json | \
jq -r '.secrets[] | "\(.key)=\(.value)"' | while IFS='=' read -r key value; do
gcloud secrets versions add "$$key" --data-file=- <<< "$$value" || \
gcloud secrets create "$$key" --data-file=- <<< "$$value"
done
secretEnv: ['KEYENV_TOKEN']
env:
- 'KEYENV_PROJECT=your-project-id'
- name: 'gcr.io/cloud-builders/gcloud'
args: ['run', 'deploy', 'my-service', '--image', 'gcr.io/$PROJECT_ID/my-service', '--region', 'us-central1']
availableSecrets:
secretManager:
- versionName: projects/$PROJECT_ID/secrets/KEYENV_TOKEN/versions/latest
env: 'KEYENV_TOKEN'
```
### Multiple Services
Sync to multiple Cloud Run services:
```bash
#!/bin/bash
SERVICES=("api" "web" "worker")
REGION="us-central1"
secrets=$(keyenv export -p YOUR_PROJECT_ID -e production --format shell)
for service in "${SERVICES[@]}"; do
echo "Syncing to $service..."
gcloud run services update "$service" \
--region="$REGION" \
--update-env-vars="$secrets"
done
```
### Terraform Integration
```hcl
# main.tf
resource "google_secret_manager_secret" "secrets" {
for_each = toset(var.secret_keys)
secret_id = each.key
replication {
auto {}
}
}
resource "google_cloud_run_v2_service" "app" {
name = "my-service"
location = "us-central1"
template {
containers {
image = "gcr.io/my-project/my-service"
dynamic "env" {
for_each = var.secret_keys
content {
name = env.value
value_source {
secret_key_ref {
secret = google_secret_manager_secret.secrets[env.value].secret_id
version = "latest"
}
}
}
}
}
service_account = google_service_account.app.email
}
}
```
### Best Practices
1. **Use Secret Manager** - Better security and automatic rotation support
2. **Grant minimal permissions** - Service accounts should only access needed secrets
3. **Use IAM conditions** - Restrict secret access by service identity
4. **Enable audit logging** - Track secret access in Cloud Audit Logs
### Troubleshooting
#### Permission Denied
Grant the Cloud Run service account access to secrets:
```bash
gcloud secrets add-iam-policy-binding SECRET_NAME \
--member="serviceAccount:YOUR_SERVICE_ACCOUNT@PROJECT.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
```
#### Service Not Restarting
Force a new revision:
```bash
gcloud run services update my-service --region=us-central1 --no-traffic
gcloud run services update-traffic my-service --region=us-central1 --to-latest
```
#### Secrets Not Mounting
Check the service configuration:
```bash
gcloud run services describe my-service --region=us-central1 --format=yaml
```
## Docker Integration
Use KeyEnv with Docker and docker-compose.
Source: https://keyenv.dev/docs/guides/docker/
This guide covers using KeyEnv with Docker and docker-compose.
### Development with docker-compose
#### Option 1: Pull secrets before starting
```bash
# Pull secrets to .env
keyenv pull
# Start containers (docker-compose reads .env automatically)
docker-compose up
```
Your `docker-compose.yml`:
```yaml
version: '3.8'
services:
app:
build: .
env_file:
- .env
ports:
- "3000:3000"
```
#### Option 2: Use keyenv run
```bash
# Start with secrets injected
keyenv run -- docker-compose up
```
This injects secrets into the docker-compose process, which passes them to containers.
### Production Deployments
#### Build-time vs Runtime Secrets
> **Warning**
>
> Never include secrets in Docker images. Always inject at runtime.
**Wrong** - Secrets baked into image:
```dockerfile
# DON'T DO THIS
COPY .env /app/.env
```
**Correct** - Secrets injected at runtime:
```yaml
# docker-compose.prod.yml
services:
app:
image: myapp:latest
env_file:
- .env.production
```
#### CI/CD Workflow
```yaml
# .github/workflows/deploy.yml
- name: Pull production secrets
env:
KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
run: keyenv pull -e production -o .env.production
- name: Deploy
run: docker-compose -f docker-compose.prod.yml up -d
```
### Docker Swarm / Kubernetes
For orchestrators, use Docker secrets or Kubernetes secrets:
#### Docker Swarm
```bash
# Pull secret and create Docker secret
keyenv get DATABASE_URL -e production -q | docker secret create db_url -
```
#### Kubernetes
For Kubernetes, we recommend using the **External Secrets Operator (ESO)** integration for automatic secret synchronization:
> **Note**
>
> See the [Kubernetes Integration Guide](/docs/guides/kubernetes) for complete ESO setup instructions.
For simple one-time syncs, you can use the CLI:
```bash
# Pull secrets and create K8s secret
keyenv pull -e production -o- | kubectl create secret generic app-secrets --from-env-file=/dev/stdin
```
### Multi-environment Setup
```bash
# Development
keyenv pull -e development -o .env.development
# Staging
keyenv pull -e staging -o .env.staging
# Production
keyenv pull -e production -o .env.production
```
```yaml
# docker-compose.yml
services:
app:
build: .
env_file:
- .env.${ENVIRONMENT:-development}
```
```bash
ENVIRONMENT=staging docker-compose up
```
### Best Practices
1. **Never commit .env files** - Add them to `.gitignore`
2. **Use .env.example** - Commit a template without values
3. **Pull fresh secrets** - Don't cache secrets in CI/CD
4. **Use different credentials** - Each environment should have unique secrets
## Kubernetes Integration
Sync KeyEnv secrets to Kubernetes using External Secrets Operator (ESO).
Source: https://keyenv.dev/docs/guides/kubernetes/
Sync KeyEnv secrets to Kubernetes using the [External Secrets Operator](https://external-secrets.io/) (ESO).
### Overview
The External Secrets Operator is a Kubernetes operator that synchronizes secrets from external providers into Kubernetes Secrets. KeyEnv provides native ESO webhook endpoints, allowing you to sync your secrets directly into Kubernetes without deploying additional infrastructure.
#### How It Works
1. ESO calls KeyEnv's webhook endpoints to fetch secret values
2. KeyEnv authenticates the request using your service token
3. ESO creates or updates Kubernetes Secrets with the fetched values
4. Secrets are automatically refreshed based on your configured interval
### Prerequisites
Before setting up the integration, ensure you have:
- **Kubernetes cluster** with kubectl access
- **External Secrets Operator** installed ([installation guide](https://external-secrets.io/latest/introduction/getting-started/))
- **KeyEnv service token** with read access to your project
#### Creating a Service Token
1. Navigate to your project in the KeyEnv dashboard
2. Go to **Settings → Service Tokens**
3. Create a new token with **Read** scope
4. Copy the token (starts with `env_`)
### Setup
#### Step 1: Create a Kubernetes Secret with Your KeyEnv Token
Store your KeyEnv service token as a Kubernetes Secret:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: keyenv-token
namespace: external-secrets
stringData:
token: "env_your_service_token_here"
```
Apply with:
```bash
kubectl apply -f keyenv-token.yaml
```
#### Step 2: Create a ClusterSecretStore
Create a ClusterSecretStore that configures ESO to communicate with KeyEnv:
```yaml
apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
name: keyenv
spec:
provider:
webhook:
url: "https://api.keyenv.dev/api/v1/eso/secret?project=&env={{ .remoteRef.property }}&key={{ .remoteRef.key }}"
result:
jsonPath: "$.value"
headers:
Authorization: "Bearer {{ .auth.token }}"
secrets:
- name: auth
secretRef:
namespace: external-secrets
name: keyenv-token
key: token
```
Replace `` with your KeyEnv project ID or slug.
Apply with:
```bash
kubectl apply -f keyenv-secretstore.yaml
```
#### Step 3: Create an ExternalSecret
Create an ExternalSecret to sync specific secrets from KeyEnv:
```yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: my-app-secrets
spec:
refreshInterval: 1h
secretStoreRef:
name: keyenv
kind: ClusterSecretStore
target:
name: my-app-secrets
data:
- secretKey: DATABASE_URL
remoteRef:
key: DATABASE_URL
property: production
- secretKey: API_KEY
remoteRef:
key: API_KEY
property: production
```
This creates a Kubernetes Secret named `my-app-secrets` containing:
- `DATABASE_URL` - fetched from KeyEnv's `production` environment
- `API_KEY` - fetched from KeyEnv's `production` environment
The `property` field specifies the KeyEnv environment, and `key` specifies the secret name.
### Bulk Export with dataFrom
To sync all secrets from an environment at once, use the bulk export endpoint with `dataFrom`.
#### Create a Bulk ClusterSecretStore
```yaml
apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
name: keyenv-bulk
spec:
provider:
webhook:
url: "https://api.keyenv.dev/api/v1/eso/secrets?project=&env={{ .remoteRef.key }}"
result:
jsonPath: "$.data"
headers:
Authorization: "Bearer {{ .auth.token }}"
secrets:
- name: auth
secretRef:
namespace: external-secrets
name: keyenv-token
key: token
```
#### Create an ExternalSecret with dataFrom
```yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: all-production-secrets
spec:
refreshInterval: 1h
secretStoreRef:
name: keyenv-bulk
kind: ClusterSecretStore
target:
name: production-secrets
dataFrom:
- extract:
key: production
```
This syncs **all secrets** from the `production` environment into a single Kubernetes Secret named `production-secrets`.
### Environment Inheritance
KeyEnv supports environment inheritance, and this is fully supported by the ESO integration:
- **Single secret**: If the requested secret is not found in the target environment, the inheritance chain is searched upward to parent environments.
- **Bulk export**: Returns all secrets from the target environment and its parent chain, with child values taking precedence over parent values for duplicate keys.
> **Note**
>
> If you've explicitly hidden an inherited secret in KeyEnv (overriding without a value), that secret will not be returned by the ESO endpoints for that environment.
### API Reference
KeyEnv provides two ESO-compatible webhook endpoints:
#### GET /api/v1/eso/secret
Fetch a single secret value.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `project` | Yes | Project ID or slug |
| `env` | Yes | Environment name or ID |
| `key` | Yes | Secret key name |
**Response:**
```json
{ "value": "secret-value-here" }
```
#### GET /api/v1/eso/secrets
Fetch all secrets as a key-value map (for ESO `dataFrom`).
| Parameter | Required | Description |
|-----------|----------|-------------|
| `project` | Yes | Project ID or slug |
| `env` | Yes | Environment name or ID |
**Response:**
```json
{
"data": {
"DATABASE_URL": "postgres://...",
"API_KEY": "sk_live_..."
}
}
```
#### Error Codes
| Status | Description |
|--------|-------------|
| 400 | Missing required parameters or circular inheritance detected |
| 401 | Invalid or missing token |
| 403 | Token lacks access to project |
| 404 | Project, environment, or secret not found |
| 500 | Internal server error |
### Troubleshooting
#### ExternalSecret Status Shows "SecretSyncedError"
Check the ExternalSecret status for details:
```bash
kubectl describe externalsecret my-app-secrets
```
Common causes:
- **401 Unauthorized**: Verify your KeyEnv token is correct and hasn't expired
- **403 Forbidden**: Ensure the token has read access to the specified project
- **404 Not Found**: Check that the secret key and environment name are correct
#### Secrets Not Updating
1. Check the `refreshInterval` on your ExternalSecret
2. Verify ESO controller is running:
```bash
kubectl get pods -n external-secrets
```
3. Check ESO controller logs:
```bash
kubectl logs -n external-secrets -l app.kubernetes.io/name=external-secrets
```
#### ClusterSecretStore Shows "NotReady"
Validate the ClusterSecretStore status:
```bash
kubectl describe clustersecretstore keyenv
```
Common issues:
- Token secret not found in the specified namespace
- Incorrect secret key name (should be `token`)
- Network connectivity issues to `api.keyenv.dev`
#### Testing the Connection
Test the KeyEnv endpoint directly:
```bash
curl -H "Authorization: Bearer env_your_token" \
"https://api.keyenv.dev/api/v1/eso/secret?project=my-project&env=production&key=DATABASE_URL"
```
A successful response returns:
```json
{ "value": "your-secret-value" }
```
### Best Practices
1. **Use dedicated service tokens** - Create a token specifically for Kubernetes with minimal permissions
2. **Set appropriate refresh intervals** - Balance between freshness and API load (1h is a good default)
3. **Use `dataFrom` for many secrets** - More efficient than individual secret syncs
4. **Monitor ESO status** - Set up alerts for sync failures
5. **Test in non-production first** - Verify your setup works before deploying to production
## Terraform Integration
Use KeyEnv secrets in your Terraform configurations.
Source: https://keyenv.dev/docs/guides/terraform/
Use KeyEnv secrets in your Terraform configurations using the external data source or CLI.
### Overview
KeyEnv provides a native Terraform provider for seamless secrets integration:
```hcl
terraform {
required_providers {
keyenv = {
source = "keyenv/keyenv"
version = "~> 1.0"
}
}
}
```
You can also integrate without the provider using the external data source or HTTP data source:
| Method | Best For | Requirements |
|--------|----------|--------------|
| **Native Provider** | All workflows | Service token only |
| **External Data Source** | Legacy workflows | KeyEnv CLI installed |
| **HTTP Data Source** | CI/CD environments | Service token only |
---
### Native Terraform Provider (Recommended)
The `keyenv/keyenv` provider fetches secrets directly via the KeyEnv API.
#### Setup
```hcl
terraform {
required_providers {
keyenv = {
source = "keyenv/keyenv"
version = "~> 1.0"
}
}
}
provider "keyenv" {
# Or set KEYENV_TOKEN environment variable
token = var.keyenv_token
}
```
#### Fetch All Secrets
```hcl
data "keyenv_environment" "prod" {
project_id = var.keyenv_project_id
name = "production"
}
data "keyenv_secrets" "prod" {
project_id = var.keyenv_project_id
environment_id = data.keyenv_environment.prod.id
}
resource "aws_db_instance" "main" {
username = data.keyenv_secrets.prod.secrets["DB_USERNAME"]
password = data.keyenv_secrets.prod.secrets["DB_PASSWORD"]
}
```
#### Fetch a Single Secret
```hcl
data "keyenv_secret" "db_url" {
project_id = var.keyenv_project_id
environment_id = data.keyenv_environment.prod.id
key = "DATABASE_URL"
}
resource "some_resource" "example" {
connection_string = data.keyenv_secret.db_url.value
}
```
#### Available Data Sources
| Data Source | Description |
|-------------|-------------|
| `keyenv_project` | Fetch project metadata by ID |
| `keyenv_environment` | Look up an environment by name |
| `keyenv_secrets` | Fetch all secrets as a map (sensitive) |
| `keyenv_secret` | Fetch a single secret by key (sensitive) |
---
### Features
- Fetch secrets at plan/apply time
- Support for any Terraform workflow
- Works with Terraform Cloud and local execution
- No state file secrets exposure (values are marked sensitive)
---
### Option 1: External Data Source (Recommended)
Use Terraform's `external` data source to call the KeyEnv CLI.
#### Prerequisites
1. Install the KeyEnv CLI:
```bash
curl -fsSL https://keyenv.dev/install.sh | bash
```
2. Authenticate with KeyEnv:
```bash
keyenv auth login
```
#### Basic Usage
```hcl
# main.tf
# Fetch all secrets from an environment
data "external" "keyenv_secrets" {
program = ["bash", "-c", <<-EOF
keyenv export --env production --format json 2>/dev/null
EOF
]
}
# Use secrets in your resources
resource "aws_db_instance" "main" {
identifier = "myapp-db"
engine = "postgres"
username = data.external.keyenv_secrets.result["DB_USERNAME"]
password = data.external.keyenv_secrets.result["DB_PASSWORD"]
}
```
#### With Service Token
For CI/CD environments, use a service token:
```hcl
# main.tf
variable "keyenv_token" {
type = string
sensitive = true
description = "KeyEnv service token"
}
variable "keyenv_project" {
type = string
description = "KeyEnv project ID"
}
variable "environment" {
type = string
default = "production"
}
data "external" "keyenv_secrets" {
program = ["bash", "-c", <<-EOF
KEYENV_TOKEN="${var.keyenv_token}" \
keyenv export \
--project "${var.keyenv_project}" \
--env "${var.environment}" \
--format json 2>/dev/null
EOF
]
}
```
#### Wrapper Script
For better error handling, create a wrapper script:
```bash
#!/bin/bash
# scripts/fetch-secrets.sh
set -euo pipefail
ENV="${1:-production}"
PROJECT="${KEYENV_PROJECT:-}"
# Build command
CMD="keyenv export --env $ENV --format json"
if [ -n "$PROJECT" ]; then
CMD="$CMD --project $PROJECT"
fi
# Execute and handle errors
if ! OUTPUT=$($CMD 2>&1); then
echo '{"error": "Failed to fetch secrets"}' >&2
exit 1
fi
echo "$OUTPUT"
```
```hcl
# main.tf
data "external" "keyenv_secrets" {
program = ["bash", "${path.module}/scripts/fetch-secrets.sh", var.environment]
}
output "secrets_loaded" {
value = length(keys(data.external.keyenv_secrets.result))
sensitive = false
}
```
---
### Option 2: HTTP Data Source
Fetch secrets directly from the KeyEnv API without the CLI.
#### Setup
```hcl
# main.tf
variable "keyenv_token" {
type = string
sensitive = true
description = "KeyEnv service token (starts with env_)"
}
variable "keyenv_project_id" {
type = string
description = "KeyEnv project ID"
}
variable "environment" {
type = string
default = "production"
}
data "http" "keyenv_secrets" {
url = "https://api.keyenv.dev/api/v1/projects/${var.keyenv_project_id}/environments/${var.environment}/secrets/export"
request_headers = {
Authorization = "Bearer ${var.keyenv_token}"
Content-Type = "application/json"
}
}
locals {
secrets_response = jsondecode(data.http.keyenv_secrets.response_body)
# Convert array to map for easy access
secrets = {
for secret in local.secrets_response.data :
secret.key => secret.value
}
}
# Use secrets
resource "aws_db_instance" "main" {
identifier = "myapp-db"
engine = "postgres"
username = local.secrets["DB_USERNAME"]
password = local.secrets["DB_PASSWORD"]
}
```
#### Error Handling
Add validation for the API response:
```hcl
locals {
secrets_response = jsondecode(data.http.keyenv_secrets.response_body)
# Validate response
secrets = data.http.keyenv_secrets.status_code == 200 ? {
for secret in local.secrets_response.data :
secret.key => secret.value
} : {}
}
# Check for errors
resource "null_resource" "validate_secrets" {
count = data.http.keyenv_secrets.status_code != 200 ? 1 : 0
provisioner "local-exec" {
command = "echo 'Error fetching secrets: ${data.http.keyenv_secrets.status_code}' && exit 1"
}
}
```
---
### Terraform Cloud / Enterprise
#### Using Environment Variables
In Terraform Cloud, set your service token as a sensitive environment variable:
1. Go to your workspace settings
2. Add a variable:
- **Key**: `TF_VAR_keyenv_token`
- **Value**: Your service token (starts with `env_`)
- **Category**: Environment variable
- **Sensitive**: Yes
#### Workspace Example
```hcl
# variables.tf
variable "keyenv_token" {
type = string
sensitive = true
description = "KeyEnv service token"
}
variable "keyenv_project_id" {
type = string
description = "KeyEnv project ID"
}
```
---
### Module Pattern
Create a reusable module for KeyEnv integration:
```hcl
# modules/keyenv-secrets/main.tf
variable "project_id" {
type = string
description = "KeyEnv project ID"
}
variable "environment" {
type = string
description = "Environment name"
}
variable "token" {
type = string
sensitive = true
description = "KeyEnv service token"
}
variable "api_url" {
type = string
default = "https://api.keyenv.dev"
}
data "http" "secrets" {
url = "${var.api_url}/api/v1/projects/${var.project_id}/environments/${var.environment}/secrets/export"
request_headers = {
Authorization = "Bearer ${var.token}"
Content-Type = "application/json"
}
}
locals {
response = jsondecode(data.http.secrets.response_body)
}
output "secrets" {
value = {
for secret in local.response.data :
secret.key => secret.value
}
sensitive = true
}
output "count" {
value = length(local.response.data)
}
```
Usage:
```hcl
# main.tf
module "keyenv" {
source = "./modules/keyenv-secrets"
project_id = "proj_abc123"
environment = "production"
token = var.keyenv_token
}
resource "aws_db_instance" "main" {
username = module.keyenv.secrets["DB_USERNAME"]
password = module.keyenv.secrets["DB_PASSWORD"]
}
```
---
### Security Best Practices
#### 1. Mark Outputs as Sensitive
Always mark secret outputs as sensitive:
```hcl
output "database_password" {
value = local.secrets["DB_PASSWORD"]
sensitive = true
}
```
#### 2. Use Minimal Token Scopes
Create service tokens with only the required permissions:
- **Read-only** access to secrets
- Scoped to specific projects
- Scoped to specific environments
#### 3. Avoid State File Exposure
Secrets fetched via data sources are stored in Terraform state. Consider:
- Using Terraform Cloud with encrypted state
- Enabling state encryption in your backend
- Using `terraform state rm` to remove sensitive data if needed
#### 4. Rotate Tokens Regularly
Use short-lived service tokens and rotate them periodically:
```hcl
variable "keyenv_token" {
type = string
sensitive = true
description = "KeyEnv service token - rotate monthly"
validation {
condition = can(regex("^env_", var.keyenv_token))
error_message = "Token must start with 'env_'"
}
}
```
---
### Troubleshooting
#### "Authentication failed"
- Verify your service token is correct
- Check the token hasn't expired
- Ensure the token has access to the specified project
#### "Project or environment not found"
- Verify the project ID is correct
- Verify the environment name matches exactly (case-sensitive)
- Check the project exists in KeyEnv
#### "External command failed"
- Ensure the KeyEnv CLI is installed and in PATH
- Run `keyenv export --env --format json` manually to debug
- Check for shell escaping issues in the external data source
#### State file contains secrets
This is expected behavior with Terraform data sources. Mitigate by:
- Using encrypted state backends
- Restricting state file access
- Using Terraform Cloud with secure state storage
---
### More Resources
- [terraform-provider-keyenv on GitHub](https://github.com/keyenv/terraform-provider-keyenv)
- [KeyEnv Service Tokens](/docs/tokens) — create a read-only token for Terraform
- [Terraform Registry](https://registry.terraform.io/providers/keyenv/keyenv)