Environment Variable

Environment Variable Concept

Environment variables are used to securely store sensitive information (passwords, API keys, certificates) or configuration values. In Apinizer, environment variables are defined at the project level and can be of two types:

• Global (All Environments): Uses the same value in all environments
• Environment-Specific: Different values can be defined for each environment

Encryption Support

Sensitive information can be stored encrypted

Level-Based

Can be defined at environment or project level

Security

Encrypted variables are stored securely

Reusability

Can be used in multiple API Proxies or Task Flows

Environment Variable Resolution Flow

The following diagram shows how environment variables are resolved at runtime and how values are retrieved according to the environment:

Value Visibility: Secret and Non-Secret

All environment variable values are stored encrypted (AES-GCM) in the database. The Secret flag does not control encryption — it controls whether the value can be read back.

Non-Secret

Used for configuration values

Values such as URLs, port numbers and flags. Stored encrypted; masked on screen, revealable with the eye icon and copyable. Returned as plain text by the read APIs and carried as plain text in an export package.

Secret

Used for information that must never be read back

Passwords, API keys, tokens. Once saved they can never be displayed: not shown on screen, returned as null from the API, and never written as plain text into an export package.

Warning

Important: A Secret value cannot be read back. To change it, you must type a new value.

What Should Be Marked Secret

• Passwords: Database passwords, API keys
• Certificates: SSL/TLS certificates
• Tokens: OAuth tokens, JWT secrets
• Other Sensitive Information: Any value nobody should be able to read back

What Does Not Need To Be Secret

• URLs: Backend API URLs
• Port Numbers: Port values
• Flags: Boolean values
• Other Configurations: General configuration values

Environment Variable Types

When an environment variable is created, one of two options is selected in the Type field:

Global (All Environments)

A single Global Value is entered

This value is the same in every environment where the variable is used. For example, a constant or a common setting that is the same in all environments.

Environment-Specific

A separate value is entered for each environment (Environment Values)

The gateway uses the value that matches the name of the environment it runs in. For example, environment-based backend URLs, API keys or database connection information.

How the Value Is Determined

The gateway resolves a ${variableName} expression by the variable's name:

• A Global variable has a single value, and this value is used in all environments.
• For an Environment-Specific variable, the value that matches the name of the environment the gateway runs in is used.
• If the variable is not found, or an environment-specific variable has no value for the active environment, the expression is replaced with an empty string ("") and the gateway writes a warning log.

Info

Environment variable names are unique across all projects and the administration level. A new variable cannot be saved with a name that already exists in another project or at the administration level.

Working Logic

1. Definition

Environment variables are defined at the project level

• Global: Same value in all environments
• Environment-Specific: Different value for each environment

2. Usage

Used in configuration fields in ${variableName} format

• Backend address: ${BACKEND_URL}
• Database: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}
• API key: ${API_KEY}

3. Runtime Resolution

Automatically resolved when API Proxy runs

• Variable expressions are detected
• Environment value is retrieved
• Secrets are decrypted
• Replaced with actual value

Example Scenario

Configuration:

• Development: BACKEND_URL = dev-api.example.com
• Production: BACKEND_URL = api.example.com
• In configuration: ${BACKEND_URL}

Runtime Results:

• In Development environment: dev-api.example.com
• In Production environment: api.example.com

Environment Variable Usage Format

Environment variables are referenced in configuration fields using a special format.

Format Structure

Format	Description	Example
${variableName}	Basic usage format	${BACKEND_URL}
text${variableName}	Combining with text	https://${API_HOST}
${variableName}text	Combining with text	${API_PORT}/api
text${variable1}text${variable2}	Multiple variables	jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}

Format Rules

Start Character

Must start with ${

End Character

Must end with }

Variable Name

Variable name in the middle (without spaces)

Case Sensitivity

Variable name is case-sensitive

Environment Variable Usage Locations

Environment variables can be used in various configuration fields in the Apinizer platform. Environment Variable Selection Dialog is only available in certain fields.

API Proxy - Routing

Upstream Routing addresses

Location: API Proxy > Upstream/Routing Tab > Define Address(es)

Used for environment-based routing in Backend API addresses.

Database Connection

Database connection configuration

Location: Administration > Connection Management > Database Connection Pool

Environment-based management in JDBC URL, Username, Password fields.

LDAP Connection

LDAP connection configuration

Location: Administration > Connection Management > LDAP Connection Pool

Environment-based management in LDAP URL, Bind DN, Bind Password fields.

API Proxy - Routing Details

Feature	Description
Location	API Proxy > Upstream/Routing Tab > Define Address(es)
Field	Backend API address input field
Usage	Environment-based routing in Backend API addresses
Access	By clicking the list icon button on the right side of the address input field

Usage Scenario: To use different backend addresses in different environments

Database Connection Details

Feature	Description
Location	Administration > Connection Management > Connection Pool Def DB
Fields	JDBC URL, Username, Password
Usage	Environment-based management in database connection information
Dialog Access	By clicking the list icon button on the right side of each field
Secret Usage	Password field must be marked as secret

Usage Scenario: To use different database connection information in different environments

LDAP Connection Details

Feature	Description
Location	Administration > Connection Management > Connection Pool Def LDAP
Fields	LDAP URL, Bind DN, Bind Password
Usage	Environment-based management in LDAP connection information
Dialog Access	By clicking the list icon button on the right side of each field
Secret Usage	Bind Password must be marked as secret

Usage Scenario: To use different LDAP connection information in different environments

Usage Scenarios and Examples

Backend API Address Management

Problem: Different backend API addresses are used in different environments.

Solution:

Creating Environment Variable:

• Key Name: BACKEND_API_URL
• Type: Environment-Specific
• Development: https://dev-api.example.com
• Test: https://test-api.example.com
• Production: https://api.example.com

Usage in Routing:

• Address: ${BACKEND_API_URL}

Result:

• In Development environment, requests go to https://dev-api.example.com
• In Test environment, requests go to https://test-api.example.com
• In Production environment, requests go to https://api.example.com

Database Connection Management

Problem: Different databases are used in each environment.

Solution:

Environment Variables:

• DB_HOST: Development=dev-db.example.com, Production=prod-db.example.com
• DB_PORT: Global=3306
• DB_NAME: Development=dev_db, Production=prod_db
• DB_USER: Development=dev_user, Production=prod_user
• DB_PASSWORD: Development=dev_pass, Production=prod_pass (Secret)

Usage in Connector:

• Connection String: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}
• Username: ${DB_USER}
• Password: ${DB_PASSWORD}

Result:

• Development: jdbc:mysql://dev-db.example.com:3306/dev_db
• Production: jdbc:mysql://prod-db.example.com:3306/prod_db

API Key Management

Problem: Different API keys are used for external services.

Solution:

Environment Variable:

• Key Name: EXTERNAL_SERVICE_API_KEY
• Type: Environment-Specific
• Development: dev-key-abc123 (Secret)
• Production: prod-key-xyz789 (Secret)

Usage in Policy:

• Header Name: X-API-Key
• Header Value: ${EXTERNAL_SERVICE_API_KEY}

Result:

• Development: X-API-Key: dev-key-abc123
• Production: X-API-Key: prod-key-xyz789

Environment Variable Creation

Environment variable creation steps:

Step 1: Adding New Environment Variable

• Go to Environment Variables page
• Click the "Create" button in the upper right corner
• Environment Variable editing window opens

Step 2: Entering Basic Information

• Key Name (Variable Name):

  • Required field
  • Must be unique within the project
  • Name check is performed automatically
  • Valid name: Green checkmark
  • Existing name: Red warning sign

• Description:

  • Optional field
  • Describes what the variable is used for

Step 3: Type Selection

• Environment-Specific:

  • Different values can be defined for each environment
  • Selected when creating new record
  • Cannot be changed after record is created

• Global (All Environments):

  • Same value used in all environments
  • Selected when creating new record
  • Cannot be changed after record is created

Info

Important: Type selection can only be done when creating a new record. The type of existing records cannot be changed.

Step 4: Value Definition

For Environment-Specific Variables:

• Adding Environment: Click "Add Environment" button to add new environment
• Environment Selection: Select an environment for each value
  • Existing environments are selected from the list
  • Custom environment name can be entered with "Custom..." option
• Entering Value: Enter value for each environment
• Secret Setting: Check "Secret" checkbox for sensitive information
  • Secret values are masked after saving (***********)
  • Secret values are stored encrypted
  • If value is not changed during update, existing value is preserved

For Global Variables:

• Global Value: Enter a single value (valid for all environments)
• Secret Setting: Check "Secret" checkbox for sensitive information

Step 5: Saving and Deployment

• Form Validation: All required fields must be filled and name must be valid
• Click "Save and Deploy" button
• Confirmation Dialog:
  • You are asked to enter the variable name again (for security)
  • Affected components are listed:
    • API Proxy Routing settings
    • Policy Configuration settings
    • Connector settings
    • Other configuration settings
• Deployment Result:
  • Automatically deployed to all running environments
  • Deployment results are shown

Warning

Important: Values marked as Secret cannot be viewed again after saving.

Environment Variable Editing

Opening the Edit Modal

The edit modal can be opened in the following ways:

Method	Description
Clicking from List	Click on the environment variable name
Selecting from Menu	Select "Edit" from the menu at the end of the row

Differences in Edit Modal

Feature	New Record	Edit
Modal Title	"Add Environment Variable"	"Edit Environment Variable"
Type Selection	Active (can be changed)	Inactive (cannot be changed)
Secret Values	Visible normally	Visible masked (***********)
Secret Checkbox	Active	Inactive for saved secrets

Best Practices

Security

• Always store sensitive information encrypted
• Use encrypted for passwords, API keys, certificates
• Regularly change passwords

Organization

• Name variables consistently
• Properly separate environment and project level variables
• Create documentation

Management

• Clean up unused variables
• Regularly review variable usage
• Perform version control

Next Steps

Variable

Learn about the Variable concept

Environment Variables

Environment Variables management

Secret Manager

Secret Manager usage

API Proxy Configuration

API Proxy configuration