YAML format specification

schemaVersion: iam.airlock.com/v1          # version of IAM YAML the format 
type: IamConfig                            # type of the configuration "IamConfig" or "IamSnippet"
metadata:                                  # metadata block with information about the configuration
  iamVersion: '8.6'                        # IAM product version the configuration is valid for
  history:                                 # Configuration history
    - datetime: 2026-02-05T12:34:56.123Z
      author: alice
      comment: Added passwordless flow
spec:                                      # The spec part contains the actual configuration
- type: SomePluginType                     # See separate examples for more information about this part.
  id: somePluginId
  properties:
    prop1: value1
    prop2: value2
modifications:                             # Config files of type snippet may contain a list of modifications.
- connectPlugin                            # See documentation about snippets and modifications.
    source: somePluginId
    destination: anotherPluginId
    destinationType: TypeOfDestinationPlugin
    property: propertyName
  

This example shows an excerpt of an IAM configuration containing main settings (GlobalConfiguration), the settings for the Loginapp and the Adminapp, and two unconnected plugins.

schemaVersion: iam.airlock.com/v1
type: IamConfig
metadata:
  iamVersion: '8.4'
spec:
  # top-level IAM modules come first
  - type: GlobalConfiguration
    ...
  - type: Loginapp
    ...
  - type: Adminapp
    ...

  # "unconnected" plugins come after the IAM modules
  - type: ApplicationId
    ...
  - type: TaskSchedule
    ...

type: LanguageSpecificTemplate
id: passwordLetterTemplateEn
displayName: English Password Letter Template
comment: Letter template texts must be approved by marketing.  
properties:
  language: en
  template: instances/common/report-templates/password-letter-en.docx

Simple properties

In general, simple properties are written as a string in YAML.

properties:

  # unquoted string value
  language: de
  resourceKey: mtan.payment.message

  # alternative representation of the same unquoted string value
  resourceKey:
  - value: mtan.payment.message   

   # quoted string values
  secretKey: '0x0000000000000000000000000000000000000000'
  pattern: '{digits:6}'

   # multiline string value
  languages: |-
    de
    fr
    en

   # numbers
  cacheTimeout: '5'
  maxRelative: '-6574'

   # boolean
  required: 'true'
  optional: 'false'

   # a list of simple values (e.g. strings or regex patterns)    languages:  
    - valueList:
        - de
        - en
        - fr
        - it 
  
   # alternative representation of the same list as above
  languages:
  - valueList: ['de', 'en', 'fr', 'it']   

Properties with plugin values

Property types with plugins as values are represented as follows. How to make multiple references to a plugin is described further below and not part of this example.

properties:
 
  # plugin property with name "authenticationSettings"  
  authenticationSettings:
    type: SomePluginType
    # rest of the plugin configuration


  # alternative representation of the above plugin property
  authenticationSettings:
  - plugin:
      type: SomePluginType
      # rest of the plugin configuration

    
  # plugin list property with name "steps"
  steps:
    - pluginList:
        - type: SomePluginType
          # rest of the plugin configuration
        - type: SomePluginType
          # rest of the plugin configuration
 
  # plugin map property with name "valueProviders"
  valueProviders:
    - pluginMap:
        mapKey1:
          type: SomePluginType
          # rest of the plugin configuration
        mapKey2:
          type: SomePluginType
          # rest of the plugin configuration

NULL values

To explicitly define NULL values (specifying the absence of a property value), the following syntax is used.

 properties:

   # simple property with explicit NULL value
   propertyName1: null

   # empty list (of simple properties)
   propertyName2:
   - valueList: []

   # plugin property with explicit NULL value
   propertyName3:
   - plugin: null

   # plugin list property with empty list
   propertyName4:
   - pluginList: []

   # plugin map property with empty map
   propertyName5:
   - pluginMap: {}

# a simple plugin tree example
type: SomePluginType
id: topLevelNode
properties:
  child1:
    type: SomePluginType
    id: childNode1
  child2:
    type: SomePluginType
    id: childNode2
    properties:
      child21:
        type: SomePluginType
        id: childNode21
      child22:
        type: SomePluginType
        id: childNode22

# use "ref" attribute to refer to plugin configurations
 type: SomePluginType
id: topLevelNode
properties:
  child1:
    type: SomePluginType
    id: childNode1
  child2:
    type: SomePluginType
    id: childNode2
    properties:
      child21:
        ref: childNode1
      child22:
        ref: childNode1

type: SomePluginType
id: idOfTheParentPlugin
properties:
  propA: parentValueA
  propB: parentValueB
  
# use a parent plugin, inherit all its properties and overwrite one of them
type: SomePluginType
id: idOfTheChildPlugin
parentRef: idOfTheParentPlugin
properties:
  propB: childValueB

Configuration contexts, environments, and variables for simple properties.

# a simple property with a combination of values depending on context, environment, and variables
properties:
  sessionIdleTimeout:
    # property value with a variable marked as sensitive (no context, no environment)
    - value: 13m
      var:
        name: SESS_TIMEOUT
        sensitive: true
    # property value for context ctxA
    - value: 17m
      context: ctxA
    # property value for environment prod
    - value: 19m
      env: prod
    # property value for environment prod and context ctxA and a variable
    - value: 23m
      env: prod
      context: ctxA
      var:
        name: SESSIONTIMEOUT

Configuration contexts, environments, and variables for a property with a simple value list.

# list of simple values with a combination of values depending on context, environment, and variables
properties:
  validLanguages:
    # property value with a sensitive variable (no context, no environment)
    - valueList:
        - de
        - en
      var:
        name: LANGDEF
        sensitive: true
    # property value for context ctxA
    - valueList:
        - de
        - fr
      context: ctxA
    # property value for environment prod
    - valueList:
        - de
        - en
        - fr
      env: prod
    # property value for environment prod and context ctxA and a variable
    - valueList:
        - de
        - it
      env: prod
      context: ctxA
      var:
        name: LANGSPEC

Configuration contexts, environments, and variables for a property with a plugin as value:

# a plugin property with a combination of values depending on context, environment, and variables
properties:
  sqlDataSource:
    # property value with a sensitive variable (no context, no environment)
    - plugin:
        ref: defaultDbConnection
      var:
        name: DBCONDEF
        sensitive: true
    # property value for context ctxA
    - plugin:
        ref: dbConnectionForContextA
      context: ctxA
    # property value for environment prod
    - plugin:
        ref: dbConnectionForEnvProd
      env: prod
    # property value for environment prod and context ctxA and a variable
    - plugin:
        ref: dbConnectionForEncProdAndContextA
      env: prod
      context: ctxA
      var:
        name: DBCONSPEC

Configuration contexts, environments, and variables for a property with a plugin list as value:

# a plugin list property with a combination of values depending on context, environment, and variables
properties:
  steps:
    # property value with a sensitive variable (no context, no environment)
    - pluginList:
        - ref: firstStepPluginId
        - ref: secondStepPluginId
      var:
        name: FLOWSTEPSDEV
        sensitive: true
    # property value for context ctxA
    - pluginList:
        - ref: firstStepPluginId
        - ref: secondStepForContextA
      context: ctxA
    # property value for environment prod
    - pluginList:
        - ref: firstStepPluginId
        - ref: secondStepForEnvProd
      env: prod
    # property value for environment prod and context ctxA and a variable
    - pluginList:
        - ref: firstStepPluginId
        - ref: secondStepForEnvProdAndContextA
      env: prod
      context: ctxA
      var:
        name: FLOWSTEPSSPEC

Configuration contexts, environments, and variables for a property with a plugin map as value:

# a plugin map property with a combination of values depending on context, environment, and variables
properties:
  valueProviders:
    # property value with a sensitive variable (no context, no environment)
    - pluginMap:
        new_email:
          ref: emailValueProviderDefault
      var:
        name: VALUEPROVIDERSDEF
        sensitive: true
    # property value for context ctxA
    - pluginMap:
        new_email:
          ref: emailValueProviderForContextA
      context: ctxA
    # property value for environment prod
    - pluginMap:
        new_email:
          ref: emailValueProviderForEnvProd
      env: prod
    # property value for environment prod and context ctxA and a variable
    - pluginMap:
        new_email:
          ref: emailValueProviderForEnvProdAndContextA
      env: prod
      context: ctxA
      var:
        name: VALUEPROVIDERSSPEC

# different ways to represent sensitive values in YAML
properties:
  # a plain secret
  password1: thisIsMyNotSoSecretPassword
  # an obfuscated (not encrypted) secret
  password2: '[OBFUSCATED]3/rzKUNND/4LElZhvcm8sNFaMXrBjLQtoNevU5BJVnk='
  # a reference to an externally stored secret
  password3:
    - value:
        storageId: idInExternallyStoredSecret
  # same as above but in combination with a configuration context
  password4:
    - value:
        storageId: idInExternallyStoredSecret
      context: ctxA