Managed Variables & Secrets

The Air Pipe platform allows you to store common variables and encrypted variables or secrets to be used across your hosted and self-hosted configurations.

Usecases

• Common variables such as endpoint addresses eg. https://commonThirdPartyService.com/api/
• Database connection strings (encrypted mode)
• Credentials (encrypted mode)

How

Adding

1. Login to the platform -> https://app.airpipe.io
2. Select the appropriate organization
3. Click on Variables in the menu
4. Click Add New
   • Enter a name and description (it is recommended to avoid overlapping names)
   • The Value is the content of your variable
   • Only select Encrypt if you are storing a sensitive variable eg. secret
     • Note: as with all encryption related tasks they will carry a performance overhead when used during the access and decryption process
   • Select the appropriate permission
     • If you are using role based permissions note that the hosted configuration or api key being used must also have the matching role to access this variable

Accessing

To substitute a managed variable the following convention is followed a|ap_var::<NameOfTheVariable>|.

• Assume we have stored a variable called MyThirdPartyService with the value of https://something.com/api/.

• This means we can access the variable with a|ap_var::MyThirdPartyService|

• We can place this for substitution in nearly any area of your configuration file

• If you selected Encrypt, the value is decrypted seamlessly at runtime.

  Access a query parameter

  actions:
      name: doSomething
      http:
          url: a|ap_var::MyThirdPartyService|/someroute?id=a|params::id|
          # ^^ access the value of `MyThirdPartyService` to build the complete url ^^

How it works

var:: vs ap_var:: vs secret::

Air Pipe has three ways to reference stored values — don't confuse them:

Marker	Source	Scope
a|var::NAME|	global.variables in the config itself	This config
a|ap_var::NAME|	Managed variables stored on the platform	Organization (shared across configs)
a|secret::NAME|	global.secrets in the config (local/Vault/AWS KMS/command — see Secrets)	This config

This page covers ap_var:: — the platform-managed variables.

Encryption

Encrypted managed variables use AES-256-GCM envelope encryption: a master key (held by the platform) protects a per-organization key, which in turn protects each value with its own nonce. Decryption happens only at runtime, at the moment of interpolation — the list/UI never returns decrypted values. Encryption adds a small per-access overhead, so only encrypt genuinely sensitive values.

Environments

A managed variable can hold a single value, or separate staging and production values. When both are set, Air Pipe picks the right one based on the environment the request runs under. When you set per-environment values you must provide both staging and production (or just the single base value) — not one on its own.

Permissions

Each variable has a permission: PUBLIC, USER_PRIVATE, USER_WITH_PUBLIC_READ (default), ROLE_PRIVATE, or ROLE_WITH_PUBLIC_READ. For the ROLE_* levels, the hosted configuration or api key accessing the variable must carry the matching role.

note

Variable names are not enforced to be unique — lookups match by organization + name and take the first result, so avoid reusing a name for different values.

Self-hosted, without an account

ap_var:: normally resolves against the platform, which needs an organization. A self-hosted engine that has never been associated with an account has no organization to ask, so before 3.6.0 the marker was skipped and interpolated to the literal text null — quietly. Since every marketplace pack is written against ap_var::, none of them could run on an air-gapped or account-less engine, and the failure looked like a successful run that happened to send the four characters n-u-l-l as your API key.

Since 3.6.0 the same markers resolve from two local sources, tried before the platform lookup:

Source	Form
Environment	AIRPIPE__AP_VAR__<NAME> — one variable per environment variable
File	AIRPIPE__AP_VAR_FILE — a path to a YAML or JSON map of name: value

# environment
export AIRPIPE__AP_VAR__OPENAI_API_KEY=sk-...
airpipe server --config-dir ./configs --api-key <key>

# or a file, which keeps values out of `ps` and shell history
cat > vars.yml <<'EOF'
OPENAI_API_KEY: sk-...
SHEET_ID: 1H4ZK...
EOF
AIRPIPE__AP_VAR_FILE=./vars.yml airpipe server --config-dir ./configs --api-key <key>

The environment wins where both define the same name. Names are matched exactly and then upper-cased, so a config written as a|ap_var::sheet_id| is served by AIRPIPE__AP_VAR__SHEET_ID. File values are stringified, so PORT: 8080 and PORT: "8080" behave identically — a marker always substitutes text.

A file that is named but cannot be read, or that is not a name: value map, logs a warning and supplies nothing rather than stopping the engine.

warning

Keep the variables file outside your --config-dir. Every file in that directory is loaded as a config, and a variables map is not one, so the engine refuses to start and names the first key it did not recognise.

Managed mode is unaffected — it resolves managed variables as it always has, and never consults these local sources.