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:

sequenceDiagram
    participant Client as 👤 Client
    participant Gateway as 🚪 API Gateway
    participant Proxy as 🔀 API Proxy
    participant Config as ⚙️ Configuration
    participant VarResolver as 🔍 Variable Resolver
    participant EnvStore as 📦 Environment Store
    participant ProjectStore as 📁 Project Store
    participant Decrypt as 🔐 Decryption
    participant Backend as 🖥️ Backend API
    
    Client->>Gateway: HTTP Request
    
    Gateway->>Proxy: Route Request to API Proxy<br/>(Environment: Production)
    
    Note over Proxy: Reading Configuration
    
    Proxy->>Config: Variable Usage Detected<br/>in Configuration<br/>${BACKEND_URL}
    
    Config->>VarResolver: Variable Resolution<br/>Request
    
    Note over VarResolver: Environment Variable<br/>Resolution Started<br/>Variable: BACKEND_URL<br/>Environment: Production
    
    VarResolver->>EnvStore: 1️⃣ Environment-Level<br/>Encrypted Check
    
    alt Environment-Level Encrypted Found
        EnvStore->>Decrypt: Encrypted Value<br/>Decrypted
        Decrypt->>VarResolver: Value Decrypted<br/>prod-api.example.com
        VarResolver->>Config: ✅ Value Returned<br/>(Highest Priority)
    else Environment-Level Encrypted Not Found
        VarResolver->>EnvStore: 2️⃣ Environment-Level<br/>Unencrypted Check
        
        alt Environment-Level Unencrypted Found
            EnvStore->>VarResolver: Value Returned<br/>prod-api.example.com
            VarResolver->>Config: ✅ Value Returned<br/>(Second Priority)
        else Environment-Level Unencrypted Not Found
            VarResolver->>ProjectStore: 3️⃣ Project-Level<br/>Encrypted Check
            
            alt Project-Level Encrypted Found
                ProjectStore->>Decrypt: Encrypted Value<br/>Decrypted
                Decrypt->>VarResolver: Value Decrypted<br/>api.example.com
                VarResolver->>Config: ✅ Value Returned<br/>(Third Priority)
            else Project-Level Encrypted Not Found
                VarResolver->>ProjectStore: 4️⃣ Project-Level<br/>Unencrypted Check
                
                alt Project-Level Unencrypted Found
                    ProjectStore->>VarResolver: Value Returned<br/>api.example.com
                    VarResolver->>Config: ✅ Value Returned<br/>(Lowest Priority)
                else Variable Not Found
                    VarResolver->>Config: ❌ Error: Variable Not Found
                end
            end
        end
    end
    
    Config->>Proxy: Configuration Resolved<br/>Backend URL: prod-api.example.com
    
    Note over Proxy: Processing Continues<br/>with Resolved Value
    
    Proxy->>Backend: Request Forwarded to Backend<br/>https://prod-api.example.com/api/products
    
    Backend->>Proxy: Response Returns<br/>200 OK
    
    Proxy->>Gateway: Processed Response
    
    Gateway->>Client: HTTP Response<br/>200 OK
    
    Note over Client,Gateway: Process Completed
    
    Note over VarResolver,Decrypt: Priority Order:<br/>1. Environment-Level Encrypted<br/>2. Environment-Level Unencrypted<br/>3. Project-Level Encrypted<br/>4. Project-Level Unencrypted<br/><br/>Encrypted values<br/>are decrypted at runtime

Environment Variable Types

Encrypted

Used for sensitive information

Sensitive information such as passwords, API keys, certificates, and tokens are stored encrypted.

uyarı

Important: Encrypted variables are encrypted irreversibly. Values are only decrypted during use.

Unencrypted

Used for configuration values

URLs, port numbers, flags, and other configuration values are stored unencrypted.

Encrypted Variables

Passwords: Database passwords, API keys
Certificates: SSL/TLS certificates
Tokens: OAuth tokens, JWT secrets
Other Sensitive Information: All values requiring security

Unencrypted Variables

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

Environment Variable Levels

Environment-Level

Valid in a specific environment

Can be used by all API Proxies and Task Flows in that environment. Has higher priority than project-level variables.

Project-Level

Valid in a specific project

Can be used by all API Proxies and Task Flows in that project. Has lower priority than environment-level variables.

Environment-Level Usage Scenarios

Environment-based backend URLs
Environment-based API keys
Environment-based configuration values
Environment-based database connection information

Project-Level Usage Scenarios

Project-based configuration values
Project-based API keys
Project-based general settings
Project-based common values

Environment Variable Priority Order

Variable resolution order (from highest to lowest):

1. Environment-Level Encrypted

Highest priority

Environment-level encrypted variables.

2. Environment-Level Unencrypted

Second priority

Environment-level unencrypted variables.

3. Project-Level Encrypted

Third priority

Project-level encrypted variables.

4. Project-Level Unencrypted

Lowest priority

Project-level unencrypted variables.

bilgi

Note: If a variable with the same name is defined at both environment and project levels, the environment-level variable is used.

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

bilgi

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

uyarı

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

Environment Variable Editing

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

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

Environment Variable Concept​

Environment Variable Resolution Flow​

Environment Variable Types​

Environment Variable Levels​

Environment Variable Priority Order​

Working Logic​

Environment Variable Usage Format​

Format Structure​

Format Rules​

Environment Variable Usage Locations​

Usage Scenarios and Examples​

Environment Variable Creation​

Environment Variable Editing​

Opening the Edit Modal​

Differences in Edit Modal​

Best Practices​

Next Steps​

Environment Variable Concept

Environment Variable Resolution Flow

Environment Variable Types

Environment Variable Levels

Environment Variable Priority Order

Working Logic

Environment Variable Usage Format

Format Structure

Format Rules

Environment Variable Usage Locations

Usage Scenarios and Examples

Environment Variable Creation

Environment Variable Editing

Opening the Edit Modal

Differences in Edit Modal

Best Practices

Next Steps