Skip to main content

Environment Variables

Environment variables let you parameterize mock responses, making them reusable across different contexts. You can scope variables to your entire organization, a specific Sandbox, or a custom profile.

Why Use Variables​

  • Reusability - Define a value once, reference it in multiple routes
  • Environment parity - Use different values in dev, staging, and production Sandboxes
  • Secret management - Store API keys and tokens securely
  • Dynamic responses - Change mock behavior without editing route definitions

Variable Scopes​

Variables are resolved in order of precedence:

  1. Profile - Highest priority, defined in a variable profile
  2. Instance - Scoped to a specific Sandbox
  3. Company - Scoped to your entire organization

When you reference a variable, SureStage uses the most specific value available.

Creating Variables​

API Request​

curl -X POST https://api.surestage.com/v1/variables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "API_BASE_URL",
    "value": "https://api.example.com",
    "scope": "instance",
    "scopeId": "sandbox_abc123",
    "isSecret": false
  }'

Response 201 Created

{
  "id": "var_xyz789",
  "key": "API_BASE_URL",
  "value": "https://api.example.com",
  "scope": "instance",
  "scopeId": "sandbox_abc123",
  "isSecret": false,
  "createdAt": "2026-03-21T10:00:00Z"
}

Parameters​

FieldTypeRequiredDescription
keystringYesVariable name (alphanumeric and underscores)
valuestringYesVariable value
scopestringYescompany, instance, or profile
scopeIdstringConditionalRequired for instance and profile scopes
isSecretbooleanNoIf true, value is encrypted at rest (default: false)

Using Variables in Routes​

Reference variables in route responses using the {{env.VARIABLE_NAME}} syntax:

{
  "method": "GET",
  "path": "/config",
  "response": {
    "status": 200,
    "body": {
      "apiUrl": "{{env.API_BASE_URL}}",
      "version": "{{env.APP_VERSION}}",
      "environment": "{{env.ENV_NAME}}"
    }
  }
}

When a request hits this route, SureStage resolves the variables:

{
  "apiUrl": "https://api.example.com",
  "version": "2.1.0",
  "environment": "staging"
}

Secret Variables​

Mark variables as secrets to encrypt them at rest. Secret values are redacted in API responses.

Create a Secret​

curl -X POST https://api.surestage.com/v1/variables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "STRIPE_API_KEY",
    "value": "sk_test_abcdef123456",
    "scope": "company",
    "isSecret": true
  }'

Retrieve a Secret​

curl https://api.surestage.com/v1/variables/var_secret123 \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "id": "var_secret123",
  "key": "STRIPE_API_KEY",
  "value": "***REDACTED***",
  "scope": "company",
  "isSecret": true,
  "createdAt": "2026-03-21T09:00:00Z"
}

You can use secrets in routes, but you cannot retrieve their plaintext values via API.

Variable Profiles​

Profiles group variables together for easy switching. Use profiles to define environment-specific variable sets.

Create a Profile​

curl -X POST https://api.surestage.com/v1/variable-profiles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "description": "Production environment variables",
    "variables": {
      "API_BASE_URL": "https://api.prod.example.com",
      "ENV_NAME": "production",
      "LOG_LEVEL": "error"
    }
  }'

Response 201 Created

{
  "id": "prof_abc123",
  "name": "Production",
  "description": "Production environment variables",
  "variables": {
    "API_BASE_URL": "https://api.prod.example.com",
    "ENV_NAME": "production",
    "LOG_LEVEL": "error"
  },
  "createdAt": "2026-03-21T10:15:00Z"
}

Apply a Profile to a Sandbox​

Set the activeProfileId on your Sandbox to activate profile variables:

curl -X PATCH https://api.surestage.com/v1/simulations/sandbox_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "activeProfileId": "prof_abc123"
  }'

All routes in the Sandbox now resolve variables from the "Production" profile first.

Resolving Variables​

Use the resolution endpoint to preview variable values for a specific context:

curl -X POST https://api.surestage.com/v1/variables/resolve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sandboxId": "sandbox_abc123",
    "profileId": "prof_abc123",
    "keys": ["API_BASE_URL", "ENV_NAME", "LOG_LEVEL"]
  }'

Response 200 OK

{
  "resolved": {
    "API_BASE_URL": {
      "value": "https://api.prod.example.com",
      "source": "profile:prof_abc123"
    },
    "ENV_NAME": {
      "value": "production",
      "source": "profile:prof_abc123"
    },
    "LOG_LEVEL": {
      "value": "error",
      "source": "profile:prof_abc123"
    }
  }
}

The source field shows where each value came from, useful for debugging precedence issues.

Managing Variables​

List Variables​

Filter by scope to see variables at a specific level:

curl "https://api.surestage.com/v1/variables?scope=instance&scopeId=sandbox_abc123" \
  -H "Authorization: Bearer $TOKEN"

Update a Variable​

curl -X PATCH https://api.surestage.com/v1/variables/var_xyz789 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "https://api.staging.example.com"
  }'

Delete a Variable​

curl -X DELETE https://api.surestage.com/v1/variables/var_xyz789 \
  -H "Authorization: Bearer $TOKEN"

Deleting a variable does not affect routes. References to deleted variables resolve to an empty string.

Security​

  • Secret variables are encrypted at rest using AES-256
  • All variable operations are protected by JwtAuthGuard and TenantGuard to prevent cross-Tenant access
  • Secret values are never included in logs or error messages
  • Variable resolution happens server-side — clients never receive raw secret values

Common Issues​

Problem: Variable not resolving in route response

Solution: Check the variable key matches exactly (case-sensitive). Use the resolution endpoint to verify the variable exists in the correct scope.

Problem: Wrong value being used

Solution: Check variable precedence. Profile variables override instance variables, which override company variables. Use the resolution endpoint to see which scope is providing the value.

Problem: Cannot retrieve secret value

Solution: Secret values are intentionally redacted in API responses. Verify the secret is working by testing the route that uses it.