--- title: "GatewayHttpApplication (config.json )" description: The GatewayHttpApplication is the entry point for all incoming gateway requests. It is responsible for initializing a heap of objects, described in Heap objects, and providing the main Handler that receives all the incoming requests. component: pinggateway version: 2023.11 page_id: pinggateway:reference:GatewayHttpApplication canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/GatewayHttpApplication.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-06-03T11:21:31Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/GatewayHttpApplication.html section_ids: config-routes-endpoint: Routes endpoint config-default-objects: Default objects sessions: Sessions GatewayHttpApplication-usage: Usage GatewayHttpApplication-properties: Properties GatewayHttpApplication-example: Example configuration files GatewayHttpApplication-default-config: Default configuration GatewayHttpApplication-doc-config: Example config.json used in the doc GatewayHttpApplication-moreinfo: More information --- # GatewayHttpApplication (`config.json` ) The GatewayHttpApplication is the entry point for all incoming gateway requests. It is responsible for initializing a heap of objects, described in [Heap objects](RequiredConfiguration.html#heap-objects), and providing the main Handler that receives all the incoming requests. The configuration is loaded from a JSON-encoded file, expected by default at `$HOME/.openig/config/config.json`. Objects configured in `config.json` can be used by `config.json` and any IG route. They cannot be used by `admin.json`. If you provide a `config.json`, the IG configuration is loaded from that file. If there is no file, the default configuration is loaded. For the default configuration, and the example `config.json` used in many of the examples in the documentation, refer to the Examples section of this page. ## Routes endpoint The endpoint is defined by the presence and content of `config.json`, as follows: * When `config.json` is not provided, the routes endpoint includes the name of the main router in the default configuration, `_router`. * When `config.json` is provided with an unnamed main router, the routes endpoint includes the main router name `router-handler`. * When `config.json` is provided with a named main router, the routes endpoint includes the provided name or the transformed, URL-friendly name. Studio deploys and undeploys routes through a main router named `_router`, which is the name of the main router in the default configuration. If you use a custom `config.json`, make sure it contains a main router named `_router`. ## Default objects IG creates objects by default in `config.json`. To override a default object, configure an object with the same name in `config.json`. Configure default objects in `config.json` and `admin.json` separately. An object configured in `config.json` with the same name as an object configured in `admin.json` is not the same object. * `BaseUriDecorator` A decorator to override the scheme, host, and port of the existing request URI. The default BaseUriDecorator is named `baseURI`. For more information, refer to [BaseUriDecorator](Decorators.html#BaseUriDecorator). - `AuditService` Records no audit events. The default AuditService is `NoOpAuditService`. For more information, refer to [NoOpAuditService](AuditFramework.html#NoOpAuditService). - `CaptureDecorator` Captures requests and response messages. The default CaptureDecorator is named `capture`, and uses the default settings given in [CaptureDecorator](Decorators.html#CaptureDecorator). When a capture point for the default CaptureDecorator is defined in a route, for example, when `"capture: "all"` is set as a top-level attribute of the JSON, log messages for requests and responses passing through the route are written to a log file in `$HOME/.openig/logs`. When no capture point is defined in a route, only exceptions thrown during request or response processing are logged. By default, request and response contexts and entities are not captured. Do one of the following to capture information: * Override the default capture decorator declaration, and set `captureEntity` to `true`. * Declare another CaptureDecorator object with an appropriate configuration and use it at your capture points. The capture decorator logs information about the HTTP request and response messages, along with their respective headers. - `ClientHandler` Communicates with third-party services. For more information, refer to [ClientHandler](Handlers.html#ClientHandler). - `ForgeRockClientHandler` Sends ForgeRock Common Audit transaction IDs when communicating with protected applications. The default ForgeRockClientHandler is a Chain, composed of a TransactionIdOutboundFilter and a ClientHandler. - `ProxyOptions` A proxy to which a [ClientHandler](ClientHandler.html) or [ReverseProxyHandler](ReverseProxyHandler.html) can submit requests, and an [AmService](AmService.html) can submit Websocket notifications. For more information, refer to [ProxyOptions](ProxyOptions.html). - `ReverseProxyHandler` Communicates with third-party services. For more information, refer to [ReverseProxyHandler](Handlers.html#ReverseProxyHandler). - `ScheduledExecutorService` Specifies the number of threads in a pool. - `SecretsService` (deprecated) Manages a store of secrets from files, system properties, and environment variables, by using Commons Secrets API. The default SecretsService is a SystemAndEnvSecretStore with the default configuration. For more information, refer to [Secrets](secrets.html). - `TemporaryStorage` Manages temporary buffers. For more information, refer to [TemporaryStorage](MiscellaneousConfigurationObjects.html#TemporaryStorage). - `TimerDecorator` Records time spent within filters and handlers. The default TimerDecorator is named `timer`. For more information, refer to [TimerDecorator](Decorators.html#TimerDecorator). - `TransactionIdOutboundFilter` Inserts the ID of a transaction into the header of a request. ## Sessions When the heap is configured with a JwtSession object named `Session`, the object is used as the default session producer. Stateless sessions are created for all requests. When a JwtSession is not configured for a request, session information is stored in the IG cookie, called by default `IG_SESSIONID`. For more information, refer to [Sessions](../about/about-sessions.html) and [JwtSession](MiscellaneousConfigurationObjects.html#JwtSession). ## Usage ```json { "handler": Handler reference, "heap": [ object, ... ], "properties": object, "secrets"(*): { "stores": [ SecretStore reference, ... ] }, "temporaryStorage": TemporaryStorage reference } ``` (\*)Deprecated ## Properties * `"handler"`: *Handler [reference](preface.html#definition-reference), required* The [Handler](Handlers.html) to which IG dispaches requests. Provide the name of a Handler object defined in the heap or an inline Handler configuration object. - `"heap"`: *array of [objects](preface.html#definition-object), optional* The heap object configuration, described in [Heap objects](RequiredConfiguration.html#heap-objects). You can omit an empty array. If you only have one object in the heap, you can inline it as the handler value. - `"properties"`: *[object](preface.html#definition-object), optional* Configuration parameters declared as property variables for use in the configuration. See also [Route properties](Properties.html). Default: Null - `"secrets"`: *SecretStore [reference](preface.html#definition-reference), optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This property is deprecated; use [SecretsProvider](SecretsProvider.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | One or more secret stores, as defined in [Secrets](secrets.html). - `"temporaryStorage"`: *TemporaryStorage [reference](preface.html#definition-reference), optional* The [TemporaryStorage](TemporaryStorage.html) object to buffer content during processing. Provide the name of a [TemporaryStorage](TemporaryStorage.html) object defined in the heap or an inline TemporaryStorage configuration object. Incoming requests use the temporary storage buffer as follows: * Used only when `streamingEnabled` is `false`. * The request is loaded into the IG storage defined in `temporaryStorage`, before it enters the chain. * If the content length of the request is more than the buffer limit, IG returns an `HTTP 413 Payload Too Large`. Default: Use the heap object named TemporaryStorage. Otherwise use an internally-created TemporaryStorage object that is named TemporaryStorage, and that uses default settings for a TemporaryStorage object. ## Example configuration files ### Default configuration When your configuration does not include a `config.json` file, the following configuration is provided by default. ```json { "heap": [ { "name": "_router", "type": "Router", "config": { "scanInterval": "&{ig.router.scan.interval|10 seconds}", "defaultHandler": { "type": "DispatchHandler", "config": { "bindings": [ { "condition": "${request.method == 'GET' and request.uri.path == '/'}", "handler": { "type": "WelcomeHandler" } }, { "condition": "${request.uri.path == '/'}", "handler": { "type": "StaticResponseHandler", "config": { "status": 405, "reason": "Method Not Allowed" } } }, { "handler": { "type": "StaticResponseHandler", "config": { "status": 404, "reason": "Not Found" } } } ] } } } } ], "handler": "_router" } ``` Notice the following features of the default configuration: * The handler contains a main router named `_router`. When IG receives an incoming request, `_router` routes the request to the first route in the configuration whose condition is satisfied. * If the request doesn't satisfy the condition of any route, it is routed to the defaultHandler. If the request is to access the IG welcome page, IG dispatches the request. Otherwise, IG returns an HTTP status 404 (Resource not found), because the requested resource does not exist. ### Example config.json used in the doc The following example of `config.json` is used in many of the examples in the documentation: ```json { "handler": { "type": "Router", "name": "_router", "baseURI": "http://app.example.com:8081", "capture": "all" }, "heap": [ { "name": "JwtSession", "type": "JwtSession" }, { "name": "capture", "type": "CaptureDecorator", "config": { "captureEntity": true, "_captureContext": true } } ] } ``` Notice the following features of the file: * The handler contains a main router named `_router`. When IG receives an incoming request, `_router` routes the request to the first route in the configuration whose condition is satisfied. * The `baseURI` changes the request URI to point the request to the sample application. * The `capture` captures the body of the HTTP request and response. * The JwtSession object in the heap can be used in routes to store the session information as JSON Web Tokens (JWT) in a cookie. For more information, refer to [JwtSession](MiscellaneousConfigurationObjects.html#JwtSession). ## More information [org.forgerock.openig.http.GatewayHttpApplication](../_attachments/apidocs/org/forgerock/openig/http/GatewayHttpApplication.html)