--- title: PingGateway reference description: This guide describes configuration options for PingGateway. It is for PingGateway designers, developers, and administrators. component: pinggateway version: 2026 page_id: pinggateway:reference:preface canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/preface.html revdate: 2025-08-26T18:26:39Z page_aliases: ["index.adoc"] section_ids: reserved-routes: Reserved routes reserved-field-names: Reserved field names field-value-conventions: Field value conventions --- # PingGateway reference This guide describes configuration options for PingGateway. It is for PingGateway designers, developers, and administrators. For API specifications, read the appropriate [Javadoc](../_attachments/apidocs/index.html). The examples in this guide use some of the following third-party tools: * `curl`: * `HTTPie`: * `jq`: * `keytool`: ## Reserved routes By default, PingGateway allows access to reserved routes only from the loopback address. To override this behavior, define an `"apiProtectionFilter"` in `admin.json`. Find an example in the documentation on [setting up UMA](../gateway-guide/uma.html#uma-configuration). You can find more information about how to change the base for administrative routes in [Change the base location](../configure/configure.html#configure-default-location). ## Reserved field names PingGateway reserves all configuration field names that contain only alphanumeric characters. If you must define your own field names, for example, in custom decorators, use names with dots, `.`, or dashes, `-`. Examples include `my-decorator` and `com.example.myDecorator`. ## Field value conventions PingGateway configuration uses [JSON](https://www.json.org/json-en.html) notation. This reference uses the following terms when referring to values of configuration object fields: * array [JSON](https://www.json.org/json-en.html) array. - boolean Either `true` or `false`. * certificate `java.security.cert.Certificate` instance. - configuration token Configuration tokens introduce variables into the PingGateway configuration. They can take values from Java system properties, environment variables, JSON, and Java properties files held in specified directories, and from properties configured in routes. Learn more in[JSON Evaluation](JsonEval.html). * duration A lapse of time expressed in English, such as `23 hours 59 minutes and 59 seconds`. Durations aren't case-sensitive and negative durations aren't supported. Use the following units in durations: * `indefinite`, `infinity`, `undefined`, `unlimited`: unlimited duration * `zero`, `disabled`: zero-length duration * `days`, `day`, `d`: days * `hours`, `hour`, `h`: hours * `minutes`, `minute`, `min`, `m`: minutes * `seconds`, `second`, `sec`, `s`: seconds * `milliseconds`, `millisecond`, `millisec`, `millis`, `milli`, `ms`: milliseconds * `microseconds`, `microsecond`, `microsec`, `micros`, `micro`, `us`, `µs`: microseconds * `nanoseconds`, `nanosecond`, `nanosec`, `nanos`, `nano`, `ns`: nanoseconds - enumeration A collection of constants. * expression Learn more in [Expressions](Expressions.html#Expressions). * configuration expression Expression evaluated at configuration time, when routes are loaded. Learn more in [Configuration expressions](Expressions.html#configuration-expression). * runtime expression Expression evaluated at runtime, for each request and response. Learn more in [Runtime expressions](Expressions.html#runtime-expression). - instant An instantaneous point on the timeline, as a Java type. Learn more in [Class Instant](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/Instant.html). * JsonValue An object (`JsonObject`), an array (`JsonArray`), a number (`JsonNumber`), a string (`JsonString`), true (`JsonValue.TRUE`), false (`JsonValue.FALSE`), or null (`JsonValue.NULL`). - lvalue-expression Expression yielding an object whose value is to be set. Properties whose format is `lvalue-expression` cannot consume streamed content. Write them with `$` instead of `#`. * map An object that maps keys to values. Keys must be unique and can map to at most one value. - number [JSON](https://www.json.org/) number. * object [JSON](https://www.json.org/) object where the content depends on the object's type. - pattern A regular expression according to the rules for the Java [Pattern](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/regex/Pattern.html) class. * pattern-template Template for referencing capturing groups in a pattern by using `$n`, where `n` is the index number of the capturing group starting from zero. For example, if the pattern is `\w+\s*=\s*(\w)+`, the pattern-template is `$1`, and the text to match is `key = value`, the pattern-template yields `value`. - reference References an object in the following ways: * An inline configuration object, where the name is optional. * A configuration expression that is a string or contains variable elements that evaluate to a string, where the string is the name of an object declared in the heap. For example, the following `temporaryStorage` object takes the value of the system property `storage.ref`, which must a be string equivalent to the name of an object defined in the heap: ```json { "temporaryStorage": "${system['storage.ref']}" } ``` * secret-id String that references a [secrets](secrets.html) managed by the Commons Secrets API. The secret ID must conform to the following regex pattern: `Pattern.compile("(\\.[a-zA-Z0-9])*");` - string [JSON](https://www.json.org/) string. * url String representation for a resource available over the Internet. Learn more in [Uniform Resource Locators (URL)](https://www.ietf.org/rfc/rfc1738.txt).