Secrets Management

This is the complete guide to implementing secrets in your ReAPI test workflows. You’ll find detailed setup instructions, advanced features, troubleshooting, and best practices.

New to secrets? Start with Security & Secrets for a quick overview and concepts. This guide assumes you understand the basics.

Subscription Feature: Secrets management is available to subscription users only.

What Are Secrets?

Secrets are encrypted variables for sensitive data like API keys, passwords, and tokens. Unlike regular variables, secrets are:

• Encrypted client-side before being sent to ReAPI servers
• Zero-knowledge: Servers cannot decrypt your secrets
• Masked in UI by default (displayed as •••••••)
• Access controlled via master password or biometric unlock
• Cached per-environment based on your security policy

Setting Up Secrets

Step 1: Create a Secured Variable Group

1. Navigate to your project’s Environments tab
2. Click New Variable Group or edit an existing group
3. Enable the Secured toggle
4. Click Save

Your variable group is now ready for secrets.

Step 2: Set Master Password

When you first add secrets to a secured variable group:

1. Click Add Secret in the variable group editor
2. You’ll be prompted to create a master password
3. Enter a strong password (16+ characters recommended)
4. Confirm the password
5. Click Create

Important: ReAPI cannot recover lost passwords due to zero-knowledge architecture. Store your password securely (use a password manager).

Step 3: Configure Cache Expiry

Cache expiry controls how long the decryption key stays in memory:

secretsCacheExpirySeconds: 14400 # 4 hours (default)

Recommended settings:

To configure:

1. Open variable group settings
2. Set Cache Expiry field
3. Click Save

Step 4: Add Secrets

1. In the secured variable group, click Add Secret
2. Enter the secret Key (e.g., API_KEY, DB_PASSWORD)
3. Enter the secret Value
4. Click Save

The secret is immediately encrypted in your browser before being stored.

Step 5: Register Biometric Device (Optional)

For convenient unlocking with fingerprint or Face ID:

1. Go to Project Settings → Security
2. Click Register Biometric Device
3. Follow your device’s biometric prompt
4. Name your device (e.g., “MacBook Pro 2024”)
5. Click Complete Registration

Requirements:

• Modern browser (Chrome 108+, Safari 16+, Edge 108+)
• Device with biometric sensor
• Platform authenticator support (macOS 13+, Windows 10+, iOS 16+)

Using Secrets in Tests

Template Engine Syntax

Access secrets in request configuration using the $secrets prefix:

# API Node - Headers
Authorization: Bearer {{$secrets.API_TOKEN}}
X-API-Key: {{$secrets.API_KEY}}
 
# API Node - Body
{
  "username": "{{username}}",
  "password": "{{$secrets.USER_PASSWORD}}"
}
 
# API Node - URL
https://api.example.com/{{$secrets.TENANT_ID}}/users

Key points:

• Regular variables: {{variableName}}
• Secrets: {{$secrets.secretName}}
• Secrets are only decrypted when needed for execution

JSONata Expressions

Access secrets in assertions, conditional logic, and context operations:

// Assertion - Check if response contains expected user
response.userId = $secrets.EXPECTED_USER_ID
 
// Context Operation - Store derived value
{
  "apiUrl": "https://" & $secrets.API_HOST & "/v1/users"
}
 
// IF Node - Conditional logic
$secrets.ENVIRONMENT = "production"
 
// Loop Node - Dynamic iteration
$secrets.MAX_RETRIES

Practical Example: Authenticated API Call

Here’s a complete example testing a user management API:

Variable Group: “Production Auth”

# Secrets (encrypted)
API_KEY: "prod-2f5a8c9e..."
ADMIN_PASSWORD: "secureP@ssw0rd123"
 
# Variables (plain text)
BASE_URL: "https://api.prod.example.com"
TIMEOUT: 5000

Test Flow: Create User

1. API Node: Get Auth Token

   Method: POST
   URL: {{BASE_URL}}/auth/login
   Headers:
     X-API-Key: {{$secrets.API_KEY}}
   Body:
     {
       "username": "admin",
       "password": "{{$secrets.ADMIN_PASSWORD}}"
     }

2. Context Operation: Store token

   {
     "authToken": response.token
   }

3. API Node: Create User

   Method: POST
   URL: {{BASE_URL}}/users
   Headers:
     Authorization: Bearer {{authToken}}
     X-API-Key: {{$secrets.API_KEY}}
   Body:
     {
       "email": "newuser@example.com",
       "role": "viewer"
     }

4. Assertion: Verify creation

   response.status = 201 and response.user.role = "viewer"

Unlocking Secrets

Password Entry

When you run a test that uses secrets:

1. ReAPI checks if decryption key is cached
2. If not cached or expired, password prompt appears
3. Enter your master password
4. Optionally check Remember for session
5. Click Unlock

The key is cached according to the variable group’s cache policy.

Biometric Unlock

If you’ve registered a biometric device:

1. Password prompt shows Use Biometric option
2. Click Use Biometric
3. Authenticate with fingerprint or Face ID
4. Key is unlocked and cached

Advantages:

• Faster than typing password
• Same security level
• No password typing (safer in shared spaces)
• Device-specific (can’t be phished)

Session Caching Behavior

Once unlocked, the decryption key remains in memory:

• Browser session: Key stored in sessionStorage
• Tab close: Key cleared automatically
• Cache expiry: Key cleared after configured duration
• Manual lock: Click lock icon to clear immediately

Security tip: For production variable groups, set cache to 0 seconds to require authentication every time.

Secrets Inheritance

Secrets inherit from parent variable groups, just like regular variables and fixtures.

How Inheritance Works

Suite Variable Group (Root)
  secrets:
    API_KEY: "shared-key-123"
    DB_HOST: "prod.db.example.com"
    DB_PASSWORD: "parent-db-pass"
│
├── Folder Variable Group (Child)
│     secrets:
│       DB_PASSWORD: "folder-db-pass"  # Overrides parent
│       FOLDER_SECRET: "xyz"           # New secret
│
│   Effective secrets in Folder:
│     API_KEY: "shared-key-123"        # Inherited
│     DB_HOST: "prod.db.example.com"   # Inherited
│     DB_PASSWORD: "folder-db-pass"    # Overridden
│     FOLDER_SECRET: "xyz"             # New
│
└── Test Case Variable Group (Leaf)
      secrets:
        DB_HOST: "test.db.example.com" # Overrides root

    Effective secrets in Test Case:
      API_KEY: "shared-key-123"        # Inherited from root
      DB_HOST: "test.db.example.com"   # Overridden
      DB_PASSWORD: "folder-db-pass"    # Inherited from folder
      FOLDER_SECRET: "xyz"             # Inherited from folder

Inheritance Rules

1. Child inherits from parent: All parent secrets are available in child
2. Child overrides parent: Same key in child replaces parent value
3. Merge order: Root → Parent → Current (left to right)
4. Decryption required: Each secured variable group must be unlocked

Practical Use Case: Multi-Environment Testing

Setup:

Root VarGroup: “Shared Credentials” (Secured)

secrets:
  API_KEY: "company-api-key-abc123"
  ENCRYPTION_KEY: "shared-encryption-key"

Child VarGroup: “Staging Environment” (Secured)

secrets:
  DB_PASSWORD: "staging-db-pass"
  ADMIN_TOKEN: "staging-admin-token"

Child VarGroup: “Production Environment” (Secured)

secrets:
  DB_PASSWORD: "prod-db-pass-secure"
  ADMIN_TOKEN: "prod-admin-token-secure"
 
# Override cache for production security
secretsCacheExpirySeconds: 0 # No cache

Result:

• Staging tests get shared API_KEY + staging-specific DB credentials
• Production tests get shared API_KEY + production-specific DB credentials
• Production requires password every time (cache = 0)
• Staging can cache for 1 hour

Unlocking with Inheritance

When a test uses multiple inherited variable groups:

1. ReAPI identifies all variable groups in hierarchy
2. Prompts for passwords for each secured group (if not cached)
3. Decrypts secrets from each group
4. Merges secrets according to inheritance rules
5. Executes test with merged secrets

Optimization: Unlock parent groups first to avoid repeated prompts.

Deployment with Secrets

When deploying tests for automated execution, you must decide how secrets are handled.

Option 1: Package Secrets in Deployment

How it works:

1. Ensure packageSecretsInDeployment is enabled (default)
2. Create deployment from test suite
3. Enter master password when prompted
4. Secrets are encrypted and included in deployment package

Pros:

• Tests run autonomously without external secret injection
• Simpler setup for CI/CD

Cons:

• Secrets stored in deployment (still encrypted)
• Must re-deploy to rotate secrets

Use case: Internal testing, staging environments, moderate security requirements

Option 2: CLI Secrets Injection

How it works:

1. Disable packageSecretsInDeployment in variable group
2. Store secrets in your own vault (AWS Secrets Manager, HashiCorp Vault, etc.)
3. Retrieve secrets in CI/CD pipeline
4. Inject secrets via CLI flag: reapi test run --secrets ./secrets.json

Pros:

• Secrets never leave your infrastructure
• Zero-knowledge extended to deployments
• Centralized secret management
• Instant rotation without re-deployment

Cons:

• Requires external secret management
• More complex CI/CD setup

Use case: Production testing, compliance requirements, maximum security

Detailed CLI usage: See CLI Usage Guide

Configuration

To control deployment packaging:

1. Open secured variable group settings
2. Toggle Package Secrets in Deployment
3. Click Save

When disabled:

• Deployment validation will fail if secrets are required but not packaged
• Must provide secrets via CLI --secrets flag
• Test runner will fail if secrets are missing

Password Prompt During Deployment

When creating a deployment with packaged secrets:

1. Click Create Deployment
2. Configure deployment settings
3. Password prompt appears for each secured variable group
4. Enter passwords to decrypt and re-encrypt secrets
5. Secrets are packaged with deployment

Tip: Unlock all variable groups before creating deployment to avoid multiple prompts.

Advanced: Secrets Authorization Control

For encrypted Variable Groups, you can restrict which users can unlock and use secrets.

Overview

Use Cases:

• Production secrets: Only senior engineers can access
• Compliance: Separate dev team from production credentials
• Vendor credentials: Only customer-facing team has access
• Financial APIs: Only authorized personnel can run payment tests

How to Configure

1. Navigate to your Variable Group settings
2. Find the Secrets Authorization section
3. Select users from the dropdown (leave empty to allow all project members)
4. Save settings

Result: Non-authorized users will see “Access Denied” when attempting to:

• View encrypted secrets
• Edit encrypted secrets
• Run tests using this Variable Group

Important Limitations

What authorization controls:

• ✅ Who can unlock secrets (view/edit in UI)
• ✅ Who can run tests with this Variable Group
• ✅ Backend API enforces access (cannot bypass)

What authorization does NOT control:

• ❌ Secrets visibility during test execution (authorized users see plaintext in requests)
• ❌ Secrets in browser memory/DevTools (authorized users have access)
• ❌ Log files with request data (may contain secrets if not sanitized)

For stricter isolation: Use CLI Secrets Injection where secrets never reach ReAPI servers.

Example Scenarios

Scenario: Production-only Access

# VarGroup: "Production Database"
# Encryption: Enabled
# Authorized Users: [alice@company.com, bob@company.com]
 
prod_db_url: postgresql://prod.db:5432/app
prod_db_password: ••••••••

Result:

• Alice and Bob: Can unlock, edit, run tests ✅
• Other team members: “Access Denied” ❌
• During test execution: Alice/Bob see secrets in requests (expected)

Scenario: Team Separation

# VarGroup: "Payment Gateway (Finance Team Only)"
# Authorized Users: [finance-team-leads]
 
stripe_secret_key: ••••••••
bank_api_key: ••••••••

Result:

• Finance team: Full access
• Engineering team: Can view VarGroup name/variables, but cannot unlock secrets
• Separation enforced at API level (backend check)

Security Boundaries

What Encrypted Mode Protects ✅

Storage Security (Data at Rest):

• Database breach: Secrets remain encrypted in storage
• ReAPI employee access: Cannot view secrets in database
• Backup/log leaks: Secrets stored as ciphertext
• Unauthorized database queries: Cannot read plaintext without password

Zero-knowledge architecture: Even if ReAPI’s servers are compromised, attackers cannot decrypt your secrets.

What Encrypted Mode Does NOT Protect ❌

Execution Security (Data in Use):

Once an authorized user unlocks secrets and runs a test:

• Secrets are visible in HTTP request headers/body
• Secrets may appear in response data
• Secrets visible in browser DevTools (Network tab)
• Secrets stored in browser memory during execution

Key Insight: Encrypted mode prevents unauthorized storage access, but authorized users can see secrets during test execution. This is by design—tests need plaintext secrets to authenticate with target APIs.

For complete isolation: Use CLI Secrets Injection to prevent secrets from being stored in ReAPI cloud entirely.

Threat Model Examples

✅ Protected: Database Breach

Attack: Hacker gains access to ReAPI’s database

Encrypted Mode Result:

• ✅ Your secrets remain safe
• ✅ Attacker sees encrypted data with no decryption keys
• ✅ Zero-knowledge prevents access

Plaintext Mode Result:

• ❌ Secrets exposed in database
• Mitigation: Use plaintext only for non-sensitive development credentials

✅ Protected: Screen Sharing Leak

Attack: You share screen while viewing secrets

Encrypted Mode Result:

• ✅ Secrets masked as ••••••• in UI by default
• ✅ Must explicitly unlock to reveal

Plaintext Mode Result:

• ❌ Secrets visible if editor is open
• Mitigation: Close secrets editor before screen sharing, or use encrypted mode for sensitive data

❌ Not Protected: Compromised Device

Attack: Malware on your laptop captures memory

Result: Cached decryption keys in memory could be extracted

• ❌ ReAPI cannot prevent local device compromises
• Mitigation:
  • Use 0-second cache for sensitive environments
  • Enable disk encryption (FileVault, BitLocker)
  • Use antivirus software
  • Lock screen when away

❌ Not Protected: Insecure Target API

Attack: Target API uses HTTP instead of HTTPS

Result: Secrets sent to API could be intercepted over network

• ❌ ReAPI protects storage, not transmission to third parties
• Mitigation:
  • Always use HTTPS endpoints
  • Verify SSL certificates
  • Use API security best practices

Test Results Encryption

ReAPI is implementing server-side encryption for test execution results as part of our zero-knowledge architecture.

What’s encrypted:

• Request and response payloads
• Headers containing secrets
• Test execution context
• Assertion results with secret values

Why it matters:

• Test results may contain sensitive data from API responses
• Server-side encryption ensures end-to-end zero-knowledge
• Compliance with data protection regulations

Status: Server-side test result encryption is currently in progress. When available, it will be enabled automatically for projects with secured variable groups.

Coming soon: Detailed documentation on test result encryption and access controls.

Troubleshooting

Password Forgotten

Problem: Lost master password, cannot access secrets

Solution:

• No recovery possible due to zero-knowledge architecture
• Must delete and recreate secured variable group
• Re-enter all secrets
• Update tests to use new variable group

Prevention:

• Store passwords in a password manager
• Document password location in team wiki
• Consider biometric unlock as backup

Biometric Device Issues

Problem: Biometric unlock not working

Solutions:

1. Device not registered: Register device in Project Settings → Security
2. Browser not supported: Update to Chrome 108+, Safari 16+, or Edge 108+
3. PRF not available: Use password unlock (device limitation)
4. Sensor not working: Check device biometric settings (System Preferences/Settings)

Workaround: Always keep password as fallback for biometric unlock.

DEK Cache Issues

Problem: Prompted for password too frequently

Solutions:

1. Check cache expiry: Increase secretsCacheExpirySeconds in variable group
2. Browser cache cleared: Cache is stored in sessionStorage (cleared on tab close)
3. Multiple variable groups: Each secured group has separate cache

Recommendations:

• Development: 4 hours (14400)
• Staging: 1-2 hours (3600-7200)
• Production: 0 seconds (0) for maximum security

Deployment Failures

Problem: Deployment creation fails with secrets error

Solutions:

1. Secrets not unlocked: Unlock all secured variable groups before deployment
2. Packaging disabled: Enable packageSecretsInDeployment or use CLI injection
3. Network timeout: Retry deployment creation

Problem: Test execution fails with “secrets not found”

Solutions:

1. Secrets not packaged: Enable packaging in variable group settings
2. CLI injection missing: Provide --secrets flag with secrets file
3. Wrong variable group: Verify test is using correct environment

Secret Value Not Applied

Problem: Test uses old secret value or empty value

Solutions:

1. Cache not cleared: Lock and unlock variable group to refresh
2. Inheritance issue: Check parent variable groups for overrides
3. Syntax error: Verify {{$secrets.KEY}} (not {{secrets.KEY}})
4. Secret not saved: Re-save secret and verify encryption

Security Checklist

Setup Phase

• Create strong master password (16+ characters, mixed case, numbers, symbols)
• Store password in password manager
• Configure cache expiry based on environment sensitivity
• Enable packageSecretsInDeployment or set up CLI injection
• Register biometric device (optional)
• Document secret keys and their purposes
• Set up variable group inheritance structure

Usage Phase

• Use {{$secrets.KEY}} syntax (not {{KEY}})
• Verify target APIs use HTTPS
• Test secret access before creating deployment
• Lock secrets when stepping away from computer
• Review test logs for accidental secret exposure

Maintenance Phase

• Rotate secrets every 90 days
• Remove unused secrets promptly
• Audit who has access to secured variable groups
• Update passwords when team members leave
• Review cache expiry settings quarterly
• Check for secrets in test names/descriptions
• Verify deployment packaging settings

Compliance Phase

• Document secret management procedures
• Train team on security best practices
• Set production cache to 0 seconds
• Use CLI injection for production deployments
• Enable audit logging (if available)
• Review security logs monthly
• Maintain secret rotation schedule

Best Practices

Choosing the Right Mode

When to use Plaintext Mode:

✅ Good for:

• Development environment credentials
• Test/staging API keys that are rotated frequently
• Shared team credentials where visibility is helpful
• Non-production databases
• Third-party sandboxes and test accounts
• Internal tool credentials with no sensitive data

❌ Bad for:

• Production API keys
• Customer data access credentials
• Payment gateway credentials (Stripe live keys, etc.)
• OAuth client secrets for production apps
• Database credentials for production systems
• Any credential that could cause real damage if leaked

When to use Encrypted Mode:

✅ Good for:

• All production credentials
• Staging/pre-production credentials that mirror production
• Customer-facing API keys
• Payment processing credentials
• OAuth secrets
• Database passwords for real data
• Any credential regulated by compliance (PCI-DSS, HIPAA, SOC2)

❌ Overkill for:

• Local development mock API keys
• Public sandbox credentials
• Test accounts with no real data

Quick Decision Tree:

1. Could this credential access real customer data? → Encrypted
2. Would a leak cause financial/legal harm? → Encrypted
3. Is this for local/dev environment only? → Plaintext
4. Do all team members need to see it? → Plaintext
5. When in doubt → Encrypted (you can always disable later)

Password Management (Encrypted Mode)

✅ Do:

• Use 20+ character passwords with mixed case, numbers, symbols
• Store in a password manager (1Password, Bitwarden, LastPass)
• Create unique passwords per project
• Enable biometric unlock for daily convenience
• Change password when team members leave
• Audit who has access quarterly

❌ Don’t:

• Use common passwords or dictionary words
• Share passwords via email, Slack, or chat
• Write passwords on paper or sticky notes
• Reuse passwords from other services
• Use predictable patterns (Password123!)

Cache Duration Strategy (Encrypted Mode)

Configure cache duration based on environment sensitivity:

Pro tip: Use biometric unlock with 0-second cache for production to get security + convenience.

Secrets Hygiene

✅ Do:

• Rotate secrets every 90 days (set calendar reminders)
• Delete secrets immediately when no longer needed
• Document what each secret is used for
• Use descriptive names (stripe_test_key not key1)
• Audit unused secrets quarterly
• Create separate secrets for test vs production

❌ Don’t:

• Store non-sensitive data as secrets (use variables instead)
• Keep old/revoked API keys
• Copy secrets to plain text variables
• Use production keys in dev environments

Team Management

✅ Do:

• Use least-privilege access (only grant what’s needed)
• Create separate Variable Groups for different security levels
• Remove access immediately when team members leave
• Audit access permissions monthly
• Use separate projects for prod vs dev teams

❌ Don’t:

• Give everyone admin access
• Share Variable Groups unnecessarily
• Delay removing departed members
• Use a single “all-access” Variable Group

Quick Reference

DO ✅

• Use secrets for all sensitive data: API keys, passwords, tokens, PII
• Rotate secrets regularly: Every 90 days or when team members leave
• Set appropriate cache expiry: 0s for production, hours for development
• Use biometric unlock: Convenient and secure
• Store passwords safely: Use a password manager
• Plan inheritance hierarchy: Shared secrets at root, specific overrides in children
• Test secret access: Before creating deployments
• Use CLI injection for production: Maximum security

DON’T ❌

• Don’t store non-sensitive data as secrets: Use regular variables for public config
• Don’t use weak passwords: Minimum 16 characters recommended
• Don’t share passwords: Each project should have unique password
• Don’t cache production secrets: Set to 0 seconds
• Don’t ignore unlock prompts: May indicate security issue
• Don’t paste secrets in chat: Use secure sharing mechanisms
• Don’t commit secrets files: Add to .gitignore

Next Steps

• Security Concepts - Understand security architecture
• Variable Groups - Learn about variable management
• CLI Usage - Set up CLI secrets injection
• API Node Guide - Use secrets in API requests

Need help? Contact support@reapi.com or join our Discord community