Creating Secrets

Learn how to create and manage encrypted secrets for API keys, passwords, and tokens.

What You’ll Learn

How to create string secrets (API keys, passwords)
How to create OAuth2 secrets (auto-refreshing tokens)
Naming conventions and best practices
Secret versioning and rotation

Creating a String Secret

String secrets are the most common type - used for API keys, passwords, tokens, and any sensitive text value.

Step 1: Navigate to Secrets

Click Resources in the sidebar
Select Secrets
Click Add Secret button

Step 2: Choose Secret Type

Select String Secret For OAuth2 tokens, see OAuth2 Secrets below.

Step 3: Enter Secret Details

Secret Name (Required)

The name you’ll use to reference this secret in routes. Format: lowercase with underscores Good examples:

stripe_prod_key
sendgrid_api_key
database_password
github_webhook_secret
twilio_auth_token
printnode_api_key

Bad examples:

secret1              (not descriptive)
StripeKey            (use lowercase)
stripe-key           (use underscores, not hyphens)
key                  (too generic)

Why naming matters: You’ll reference secrets in templates like this:

{{secret:stripe_prod_key}}

Clear names make your configurations self-documenting.

Secret Value (Required)

The actual sensitive value to encrypt and store. Examples:

API keys:      sk_live_abc123xyz789...
Passwords:     MySecureP@ssw0rd!2024
Tokens:        eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
URLs:          postgres://user:pass@host:5432/db
Webhook secrets: whsec_abc123xyz789...

Important:

Copy from source carefully (no extra spaces!)
Value is encrypted immediately after saving
You won’t be able to view plaintext again

Description (Optional but Recommended)

Document what this secret is for and when to rotate it. Good descriptions:

"Stripe production API key - rotate every 90 days"
"SendGrid API key for transactional emails"
"Database connection string for prod PostgreSQL"
"GitHub webhook secret for repository events"
"Twilio auth token for SMS - expires Dec 2025"

Why descriptions help:

Remember what each secret is for
Track rotation schedules
Know where it’s used
Easier team collaboration

Tags (Optional)

Add tags to organize secrets. Useful tags:

production, staging, dev
payment, email, sms, database
third-party, internal
critical, standard

Example:

Secret: stripe_prod_key
Tags: production, payment, third-party, critical

Step 4: Save

Click Create Secret ✅ Done! Your secret is now:

Encrypted with AES-256-GCM
Stored securely
Ready to use in routes

⚠️ Important: The plaintext value is now gone from the UI. If you need to reference it later, you’ll need to get it from the original source.

Creating OAuth2 Secrets

OAuth2 secrets are special - they automatically refresh access tokens when they expire.

When to Use OAuth2 Secrets

Use OAuth2 for services that require token refresh:

✅ Google APIs (Gmail, Drive, Sheets)
✅ Microsoft Graph (Office 365, OneDrive)
✅ Shopify
✅ HubSpot
✅ Salesforce
✅ Slack

Step 1: Choose OAuth2 Secret Type

When creating secret, select OAuth2 Secret

Step 2: Fill in OAuth2 Details

Secret Name

google_oauth_token
shopify_access_token
hubspot_oauth_creds

OAuth2 Configuration

Client ID:

123456789.apps.googleusercontent.com

From your OAuth app settings Client Secret:

GOCSPX-abc123xyz789...

From your OAuth app settings Access Token:

ya29.a0AfH6SMBx...

Initial access token from OAuth flow Refresh Token:

1//0gABC123XYZ...

Refresh token to get new access tokens Token URL:

https://oauth2.googleapis.com/token

Where to refresh tokens Expires At:

2025-01-15T10:30:00Z

When current token expires

Step 3: Save

Click Create Secret ✅ Auto-refresh enabled! KnoxCall will:

Monitor token expiry
Refresh before expiration
Update access token automatically
Log refresh events

Secret Naming Conventions

Pattern: `{service}_{environment}_{type}`

Examples:

By Service

stripe_prod_key
stripe_staging_key
sendgrid_prod_api_key
twilio_dev_token

By Environment

database_prod_password
database_staging_password
database_dev_password

By Purpose

webhook_secret_github
webhook_secret_shopify
api_key_printnode
api_key_openai

Multiple Secrets for Same Service

When you need different keys for different purposes:

stripe_prod_live_key          (live transactions)
stripe_prod_restricted_key    (read-only)
stripe_test_key               (testing)

Environment-Specific Secrets

Create separate secrets for each environment:

Production Secrets

Name: stripe_prod_key
Value: sk_live_abc123...
Description: Stripe production - live transactions
Tags: production, payment, critical

Staging Secrets

Name: stripe_staging_key
Value: sk_test_xyz789...
Description: Stripe staging - test mode
Tags: staging, payment

Development Secrets

Name: stripe_dev_key
Value: sk_test_dev123...
Description: Stripe development - local testing
Tags: development, payment

Then use in route overrides:

Production environment:
  Header: Authorization: Bearer {{secret:stripe_prod_key}}

Staging environment:
  Header: Authorization: Bearer {{secret:stripe_staging_key}}

Development environment:
  Header: Authorization: Bearer {{secret:stripe_dev_key}}

Best Practices

✅ Do

1. Use descriptive names

✅ stripe_prod_live_key
❌ key1

2. Document with descriptions

✅ "Stripe production API key - rotate every 90 days - expires Mar 2025"
❌ (no description)

3. Separate by environment

✅ stripe_prod_key, stripe_staging_key, stripe_dev_key
❌ stripe_key (used everywhere)

4. Tag appropriately

✅ Tags: production, payment, critical
❌ (no tags)

5. Version for rotation

Secret v1: stripe_prod_key (old)
Secret v2: stripe_prod_key (new, rotated)

6. Use OAuth2 type when applicable

✅ OAuth2 secret for Google APIs (auto-refresh)
❌ String secret that expires (manual update needed)

❌ Don’t

1. Don’t commit secrets to git

❌ .env file in repository
✅ Store in KnoxCall secrets

2. Don’t reuse across environments

❌ Same key for prod and dev
✅ Separate keys per environment

3. Don’t use generic names

❌ api_key, secret, password
✅ stripe_prod_key, database_prod_password

4. Don’t skip descriptions

❌ No description
✅ "Production database - rotate quarterly - last rotated Jan 2025"

5. Don’t expose test keys in production

❌ stripe_test_key in production environment
✅ stripe_prod_key in production

Secret Security

How Secrets Are Stored

Encryption: AES-256-GCM (military-grade)
Envelope encryption: Each secret has unique encryption key
Master key: Stored separately, never exposed
Integrity: SHA-256 checksum verification

Who Can Access Secrets

View encrypted secrets:

All team members with access

View plaintext values:

Nobody - not even admins!
Plaintext only visible when:
- Initially created (one-time viewing)
- Decrypted server-side during requests
- Never shown in logs or UI

Use secrets in routes:

Anyone with route edit permissions

Secret Transmission

When requests use secrets:

Client makes request to KnoxCall
KnoxCall loads route config
Sees {{secret:stripe_key}} template
Decrypts secret server-side
Injects into request to backend
Client never sees plaintext!

Common Use Cases

1. Payment APIs

Stripe:

Name: stripe_prod_key
Value: sk_live_abc123xyz789...
Description: Stripe production secret key

Usage in route:

{
  "Authorization": "Bearer {{secret:stripe_prod_key}}"
}

2. Email Services

SendGrid:

Name: sendgrid_api_key
Value: SG.abc123xyz789...
Description: SendGrid API key for transactional emails

Usage:

{
  "Authorization": "Bearer {{secret:sendgrid_api_key}}"
}

3. SMS Services

Twilio:

Name: twilio_auth_token
Value: abc123xyz789...
Description: Twilio auth token for SMS

Usage:

{
  "Authorization": "Basic {{secret:twilio_auth_token}}"
}

4. Database Credentials

PostgreSQL:

Name: database_prod_url
Value: postgres://user:pass@host:5432/db
Description: Production database connection string

Usage in body:

{
  "connection_string": "{{secret:database_prod_url}}"
}

5. Webhook Secrets

GitHub:

Name: github_webhook_secret
Value: whsec_abc123...
Description: GitHub webhook verification secret

Usage:

{
  "X-Hub-Signature": "{{secret:github_webhook_secret}}"
}

6. Printing Services

PrintNode:

Name: printnode_api_key
Value: abc123xyz789...
Description: PrintNode API key for cloud printing

Usage:

{
  "Authorization": "Basic {{secret:printnode_api_key}}"
}

Secret Versioning

KnoxCall tracks secret versions for safe rotation.

Creating a New Version

When rotating a secret:

Go to Secrets
Click on secret name
Click Add New Version
Enter new value
Save

What happens:

New version becomes active immediately
Old version preserved (for rollback)
All routes using secret now use new value
Zero downtime!

Viewing Version History

Click secret name
Go to Version History tab
See all versions with timestamps
Can rollback if needed

Troubleshooting

Secret Not Found in Templates

Error: Secret 'stripe_key' not found Causes:

Typo in secret name
Secret was deleted
Wrong syntax in template

Solution:

Check secret exists: Resources → Secrets
Verify spelling matches exactly
Check template syntax: {{secret:name}}

Cannot View Secret Value

Symptom: Want to see what the value is. Cause: Plaintext never shown after creation (security feature). Solution:

Get value from original source
Or create new version with known value

Secret Not Injecting

Symptom: Backend receives literal {{secret:stripe_key}} text. Causes:

Template syntax error
Secret doesn’t exist
Injection disabled

Debug:

Check logs - what was actually sent?
Verify template syntax is correct
Test secret exists and name matches
Verify inject headers is enabled on route

Quick Reference

Task	Steps
Create string secret	Resources → Secrets → Add Secret → String
Create OAuth2 secret	Resources → Secrets → Add Secret → OAuth2
Rotate secret	Click secret → Add New Version
View versions	Click secret → Version History
Delete secret	Click secret → Delete (⚠️ permanent)

Next Steps

Using Secrets

How to inject secrets into routes

Secrets Overview

Complete secrets guide

OAuth2 Flow

Set up OAuth2 auto-refresh

Rotation Strategies

Best practices for rotating secrets

Security Reminder: Never commit secrets to git, share via email, or hardcode in applications. Always use KnoxCall’s encrypted secret storage.

Getting Started

Essentials: Routes

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Webhooks

Workflows

Security

Monitoring

Advanced Features

Infrastructure

Account

Troubleshooting

Support

About

​Creating Secrets

​What You’ll Learn

​Creating a String Secret

​Step 1: Navigate to Secrets

​Step 2: Choose Secret Type

​Step 3: Enter Secret Details

​Secret Name (Required)

​Secret Value (Required)

​Description (Optional but Recommended)

​Tags (Optional)

​Step 4: Save

​Creating OAuth2 Secrets

​When to Use OAuth2 Secrets

​Step 1: Choose OAuth2 Secret Type

​Step 2: Fill in OAuth2 Details

​Secret Name

​OAuth2 Configuration

​Step 3: Save

​Secret Naming Conventions

​Pattern: {service}_{environment}_{type}

​By Service

​By Environment

​By Purpose

​Multiple Secrets for Same Service

​Environment-Specific Secrets

​Production Secrets

​Staging Secrets

​Development Secrets

​Best Practices

​✅ Do

​❌ Don’t

​Secret Security

​How Secrets Are Stored

​Who Can Access Secrets

​Secret Transmission

​Common Use Cases

​1. Payment APIs

​2. Email Services

​3. SMS Services

​4. Database Credentials

​5. Webhook Secrets

​6. Printing Services

​Secret Versioning

​Creating a New Version

​Viewing Version History

​Troubleshooting

​Secret Not Found in Templates

​Cannot View Secret Value

​Secret Not Injecting

​Quick Reference

​Next Steps

Using Secrets

Secrets Overview

OAuth2 Flow

Rotation Strategies

Creating Secrets

What You’ll Learn

Creating a String Secret

Step 1: Navigate to Secrets

Step 2: Choose Secret Type

Step 3: Enter Secret Details

Secret Name (Required)

Secret Value (Required)

Description (Optional but Recommended)

Tags (Optional)

Step 4: Save

Creating OAuth2 Secrets

When to Use OAuth2 Secrets

Step 1: Choose OAuth2 Secret Type

Step 2: Fill in OAuth2 Details

Secret Name

OAuth2 Configuration

Step 3: Save

Secret Naming Conventions

Pattern: `{service}_{environment}_{type}`

By Service

By Environment

By Purpose

Multiple Secrets for Same Service

Environment-Specific Secrets

Production Secrets

Staging Secrets

Development Secrets

Best Practices

✅ Do

❌ Don’t

Secret Security

How Secrets Are Stored

Who Can Access Secrets

Secret Transmission

Common Use Cases

1. Payment APIs

2. Email Services

3. SMS Services

4. Database Credentials

5. Webhook Secrets

6. Printing Services

Secret Versioning

Creating a New Version

Viewing Version History

Troubleshooting

Secret Not Found in Templates

Cannot View Secret Value

Secret Not Injecting

Quick Reference

Next Steps