--- title: Token Resolution description: Understand how PingGateway resolves configuration tokens using route resolvers, environment variables, system properties, and token source files component: pinggateway version: 2026 page_id: pinggateway:reference:TokenResolvers canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/TokenResolvers.html revdate: 2026-01-12 section_ids: tokensub-route-resolver: Route Token Resolvers tokensub-env-variables: Environment Variables Resolver tokensub-sys-properties: System Properties Resolver tokensub-prop-files: Token Source File Resolvers --- # Token Resolution At startup, the bootstrap resolver builds a chain of resolvers to resolve configuration tokens included in `config.json` and `admin.json`. When a route is deployed, *route resolvers* build on the chain to add resolvers for the route. ## Route Token Resolvers When a route is deployed in PingGateway a route resolver is created to resolve the configuration tokens for the route. The resolver uses token values defined in the `properties` section of the route. If the token can't be resolved locally, the route resolver accesses token values recursively in a parent route. Learn more about route properties in [PingGateway route properties](Properties.html). ## Environment Variables Resolver When the bootstrap resolver resolves a configuration token to an environment variable, it replaces the lowercase and periods (`.`) in the token to match the convention for environment variables. Environment variable keys are transformed as follows: * Periods (.) are converted to underscores * All characters are transformed to uppercase The following example sets the value of an environment variable for the port number: ```console $ export LISTEN_PORT=8080 ``` In the following PingGateway configuration, the value of `port` is `8080`: ```json { "port": { "$int": "&{listen.port}" } } ``` ## System Properties Resolver The system property name must match a configuration token exactly. The following example sets a system property for a port number: ```console $ java -Dlisten.port=8080 -jar start.jar ``` In the following PingGateway configuration, the value of `port` is `8080`: ```json { "port": { "$int": "&{listen.port}" } } ``` ## Token Source File Resolvers Token source files have the `.json` or `.properties` extension. The bootstrap resolver uses the files to add file resolvers to the chain of resolvers: * **JSON file resolvers** Token source files with the `.json` extension take a JSON format. The token name is mapped either to the JSON attribute name or to the JSON path. Each of the following `.json` files set the value for the configuration token `product.listen.port`: ```json { "product.listen.port": 8080 } ``` ```json { "product.listen": { "port": 8080 } } ``` ```json { "product": { "listen": { "port": 8080 } } } ``` * **Properties file resolvers** Token source files with the `.properties` extension are Java properties files. They contain a flat list of key/value pairs, and keys must match tokens exactly. The following `.properties` file also sets the value for the tokens `listen.port` and `listen.address`: ```properties listen.port=8080 listen.address=192.168.0.10 ``` PingGateway stores token source files in one or more directories defined by the environment variable `IG_ENVCONFIG_DIRS` or the system property `ig.envconfig.dirs`. By default, these settings use UTF-8 encoding. To use deprecated ISO-8859-1 encoding, set the deprecated system property `org.forgerock.config.resolvers.properties.encoding` to `ISO-8859-1`. If token source files are in multiple directories, each directory must be specified in a comma-separated list. PingGateway doesn't scan subdirectories. The following example sets an environment variable to define two directories that hold token source files: ```console $ export IG_ENVCONFIG_DIRS="/myconfig/directory1,/myconfig/directory2" ``` At startup, the bootstrap resolver scans the directories in the specified order, and adds a resolver to the chain of resolvers for each token source file in the directories. Although the bootstrap resolver scans the directories in the specified order, within a directory it scans the files in a nondeterministic order. Note the following constraints for using the same configuration token more than once: * Don't define the same configuration token more than once in a single file. There is no error, but you won't know which token is used. * Don't define the same configuration token in more than one file in a single directory. An error occurs. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------- | | | This constraint implies that you can't have backup `.properties` and `.json` files in a single directory if they define the same tokens. | * You can define the same configuration token once in several files that are located in different directories, but the first value that PingGateway reads during JSON evaluation is used. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When logging is enabled at the DEBUG level for token resolvers, the origin of the token value is logged.If you are using the default logback implementation, add the following line to your `logback.xml` to enable logging:```xml ``` |