Storing Secrets

Storing sensitive data in Checkly

Secrets in Checkly are a specialized form of data designed specifically for sensitive information that needs to be kept secure while remaining accessible to your monitoring. Secrets allow you to store sensitive data for use in checks. Once saved secrets are never shown in the UI or in logs. The secret value cannot be accessed via the CLI or API.

Secrets handle the truly sensitive elements—API keys, passwords, authentication tokens, and any other information that could compromise security if exposed.

Both variables and secrets are encrypted at rest and in flight. However, Secrets go further by ensuring that once stored, their values become completely invisible to users, appearing only as masked values in interfaces while remaining fully functional in your monitoring code.

Secrets in Practice

Secrets integrate seamlessly into your monitoring workflow while maintaining security. You reference them in your code using the same syntax as regular environment variables, but they remain protected throughout the entire execution pipeline. This means you can write monitoring logic that authenticates with services, accesses protected endpoints, and performs realistic user scenarios without compromising security.

Use secrets in your scripts using standard Node.js syntax: process.env.MY_SECRET or by using {{handlebars}} syntax in applicable API check fields.

Real-World Secrets Examples

Here’s how you might use Secrets in real monitoring scenarios:

API Authentication Example:

import { ApiCheck, AssertionBuilder } from 'checkly/constructs'

new ApiCheck('authenticated-api-check', {
  name: 'User Profile API',
  request: {
    method: 'GET',
    url: 'https://api.example.com/user/profile',
    headers: {
      // Secret API key - never visible in logs or UI
      'Authorization': 'Bearer {{API_SECRET_KEY}}',
      'Content-Type': 'application/json'
    },
    assertions: [
      AssertionBuilder.statusCode().equals(200),
      AssertionBuilder.jsonBody('user.email').isNotNull()
    ]
  }
})

Browser Login Flow Example:

import { test, expect } from '@playwright/test'

test('Login flow', async ({ page }) => {
  await page.goto('https://app.example.com/login')
  
  // Using secrets for login credentials
  await page.fill('#email', process.env.TEST_USER_EMAIL!)
  await page.fill('#password', process.env.TEST_USER_PASSWORD!)
  
  await page.click('#login-button')
  
  // Verify successful login
  await expect(page.locator('.dashboard')).toBeVisible()
})

Database Connection Example:

import { ApiCheck } from 'checkly/constructs'

new ApiCheck('database-health-check', {
  name: 'Database Health Check',
  request: {
    method: 'POST',
    url: 'https://api.example.com/health/database',
    headers: {
      'Authorization': 'Bearer {{DB_MONITORING_TOKEN}}'
    },
    body: JSON.stringify({
      // Secret database connection string
      connectionString: '{{DATABASE_CONNECTION_STRING}}'
    })
  }
})

Managing Secrets via CLI:

# Create a secret
npx checkly env add API_SECRET_KEY your_secret_api_key_here --secret

# Create a secret for database credentials
npx checkly env add DATABASE_PASSWORD super_secret_password --secret

# List all variables (secrets show only key names)
npx checkly env ls

# Update a secret (must include --secret flag)
npx checkly env update API_SECRET_KEY new_secret_value --secret

Payment Processing Example:

import { test } from '@playwright/test'

test('Checkout flow with test payment', async ({ page }) => {
  await page.goto('https://shop.example.com/checkout')
  
  // Fill checkout form
  await page.fill('#card-number', process.env.TEST_CARD_NUMBER!)
  await page.fill('#card-expiry', process.env.TEST_CARD_EXPIRY!)
  await page.fill('#card-cvc', process.env.TEST_CARD_CVC!)
  
  // Process payment
  await page.click('#pay-button')
  
  // Verify success
  await expect(page.locator('.payment-success')).toBeVisible()
})

Secrets as Security Foundation

Secrets represent the foundation of secure monitoring practices. They enable you to test and monitor authenticated workflows, private APIs, and sensitive user journeys while maintaining the security posture that modern applications require. By centralizing secret management within your monitoring platform, you eliminate the risk of credentials being scattered across scripts, configuration files, or team communications.

The power of Secrets lies in making security invisible to your monitoring logic—your Checks work exactly the same whether they’re using public endpoints or accessing the most sensitive parts of your application, but the security model ensures that sensitive information never leaves the protected environment.

Alternative: Dynamic Secret Detection

For browser checks and multistep checks, you can also use dynamic secret detection. This approach allows you to retrieve secrets at runtime (from external vaults like Azure Key Vault, AWS Secrets Manager, etc.) and have them automatically scrubbed from logs and traces.

// Example: Retrieve from external vault at runtime
process.env.CHECKLY_SECRET_API_KEY = await getFromAzureKeyVault('api-key')
process.env.CHECKLY_SECRET_TOKEN = await fetchFromAWS('auth-token')

This is particularly useful for organizations that prefer not to store secrets in Checkly and want to maintain their existing secret management infrastructure. Learn more about dynamic secret scrubbing.

Using secrets in alert channels

Secrets also work in alert-channel configurations — webhook URLs, API keys, PagerDuty service keys, and any other literal-secret field accept the same {{NAME}} reference syntax. See Alert channels for details and the inline promote-to-secret affordance.

Security and Usability Balance

Use dedicated test users, test cards etc. These test users should have minimal privileges in your app. Do not use your admin or root user. Make sure you can easily disable or block these users without recourse.

Keep secrets separate from your browser scripts and store them as environment secrets in Checkly. This way you can reuse secrets in multiple scripts and rotate them as needed.