Skip to main content
Secrets Management

​
What You’ll Accomplish

Secrets Management lets you connect to databases and servers without exposing credentials to users. Instead of sharing passwords, you can:
  • Store credentials in HashiCorp Vault, AWS Secrets Manager, or other providers
  • Inject secrets at runtime—users never see the actual values
  • Rotate credentials without updating connection configs
  • Audit who accessed what, without credential exposure

​
How It Works

1

Store Secrets

Save credentials in your secrets provider (Vault, AWS, etc.)
2

Reference in Connection

Configure connections using secret references like _envs/vault/DB_PASSWORD
3

Runtime Resolution

When a user connects, Hoop fetches the secret and injects it
4

Secure Access

User connects successfully without ever seeing the credential

​
What Users See

When a user connects to a database configured with secrets: 
$ hoop connect prod-postgres
Connected to prod-postgres
psql>
They connect successfully, but never see the database password. The password is fetched from Vault and injected by Hoop.

​
Supported Providers

HashiCorp Vault

Most popular self-hosted secrets manager

AWS Secrets Manager

AWS-native secrets storage

Azure Key Vault

Azure-native key and secret management

GCP Secret Manager

Google Cloud secrets storage

Environment Variables

Simple secrets via gateway environment

Kubernetes Secrets

Native Kubernetes secret references

​
Quick Start

​
Example: HashiCorp Vault

​
Step 1: Store a Secret in Vault

vault kv put secret/databases/prod-postgres \
  username=app_user \
  password=supersecretpassword

​
Step 2: Configure Hoop Gateway

Set environment variables for Vault access: 
VAULT_ADDR=https://vault.example.com:8200
VAULT_TOKEN=hvs.your-vault-token

​
Step 3: Create Connection with Secret Reference

In the Web App or via CLI, create a connection that references the secret: 
hoop admin create connection prod-postgres \
  --agent default \
  --type postgres \
  -- psql "postgresql://_envs/vault/secret/databases/prod-postgres#username:_envs/vault/secret/databases/prod-postgres#password@db.example.com:5432/myapp"
Or configure in the Web App:
  • Username: _envs/vault/secret/databases/prod-postgres#username
  • Password: _envs/vault/secret/databases/prod-postgres#password

​
Step 4: Test the Connection

hoop connect prod-postgres
The connection works, with credentials fetched from Vault at runtime.

​
Secret Reference Syntax

Secrets are referenced using a special syntax: 
_envs/<provider>/<path>#<key>
ComponentDescriptionExample
_envs/Prefix indicating a secret reference
<provider>Secret provider namevault, aws, azure, gcp
<path>Path to the secret in the providersecret/databases/prod
#<key>(Optional) Specific key within the secret#password

​
Examples

HashiCorp Vault: 
_envs/vault/secret/databases/prod-postgres#password
AWS Secrets Manager: 
_envs/aws/prod/databases/postgres#password
Environment Variable: 
_envs/DB_PASSWORD

​
Provider Configuration

​
HashiCorp Vault

Gateway environment variables:
VariableDescription
VAULT_ADDRVault server URL
VAULT_TOKENAuthentication token
VAULT_NAMESPACE(Optional) Vault namespace
Reference format: 
_envs/vault/<mount>/<path>#<key>

​
AWS Secrets Manager

Gateway environment variables:
VariableDescription
AWS_REGIONAWS region
AWS_ACCESS_KEY_IDAWS access key
AWS_SECRET_ACCESS_KEYAWS secret key
Or use IAM roles for EC2/ECS. Reference format: 
_envs/aws/<secret-name>#<key>

​
Azure Key Vault

Gateway environment variables:
VariableDescription
AZURE_VAULT_URLKey Vault URL
AZURE_CLIENT_IDService principal client ID
AZURE_CLIENT_SECRETService principal secret
AZURE_TENANT_IDAzure tenant ID
Reference format: 
_envs/azure/<secret-name>

​
GCP Secret Manager

Gateway environment variables:
VariableDescription
GCP_PROJECT_IDGoogle Cloud project
GOOGLE_APPLICATION_CREDENTIALSPath to service account JSON
Reference format: 
_envs/gcp/<secret-name>

​
Use Cases

​
1. Database Credentials

Store database passwords in Vault instead of connection configs: 
# Instead of this (insecure):
password: mysecretpassword

# Use this (secure):
password: _envs/vault/secret/databases/prod#password

​
2. API Keys

Inject API keys for application connections: 
# Command that needs an API key
curl -H "Authorization: Bearer _envs/vault/secret/api-keys/stripe#key" https://api.stripe.com/v1/charges

​
3. SSH Keys

Store SSH private keys securely: 
ssh -i _envs/vault/secret/ssh-keys/prod-server#private_key user@server.example.com

​
4. Kubernetes Secrets

For agents running in Kubernetes, reference native secrets: 
_envs/k8s/my-namespace/db-credentials#password

​
Credential Rotation

One of the biggest benefits of secrets management is seamless credential rotation:
1

Update Secret in Provider

Change the password in Vault/AWS/etc.
2

No Connection Changes Needed

Connection configs reference the secret, not the value
3

New Connections Use New Credential

Next time someone connects, they get the new password

​
Rotation Best Practices

  1. Schedule regular rotations - Monthly or quarterly
  2. Test after rotation - Verify connections still work
  3. Keep previous version - Some providers support versioning
  4. Audit access - Check who accessed secrets recently

​
Troubleshooting

​
Connection Fails with “Secret Not Found”

Check:
  1. Secret path is correct (including mount point for Vault)
  2. Provider credentials are configured on the gateway
  3. Provider is accessible from the gateway network
  4. Secret exists and has the expected key
Debug: 
# Test Vault access from gateway
vault kv get secret/databases/prod-postgres

# Test AWS access
aws secretsmanager get-secret-value --secret-id prod/databases/postgres

​
“Permission Denied” Errors

Check:
  1. Gateway credentials have read access to the secret
  2. Vault policy allows reading the path
  3. IAM role/policy includes the secret ARN

​
Secret Value Not Substituted

If you see the literal _envs/... string instead of the secret value:
  1. Check the syntax is exactly correct
  2. Verify provider is configured in gateway environment
  3. Restart the gateway after configuration changes

​
Security Best Practices

Least Privilege

Grant gateway only read access to needed secrets

Audit Logging

Enable audit logs on your secrets provider

Rotate Regularly

Schedule regular credential rotation

Separate by Environment

Use different secrets for dev/staging/prod

​
What NOT to Do

  • Don’t store secrets in connection configs directly
  • Don’t share provider tokens with users
  • Don’t use the same credentials across environments
  • Don’t skip rotation because “it’s working”

​
Next Steps

Configuration Guide

Detailed provider setup instructions

Access Control

Control who can access connections

Session Recording

Audit all connection activity

HashiCorp Vault

Vault documentation