--- 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: 2026 page_id: pinggateway:reference:GatewayHttpApplication canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/GatewayHttpApplication.html revdate: 2026-02-23T12:00:00Z section_ids: config-routes-endpoint: Routes endpoint config-default-objects: Default objects 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 documentation 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](heap-objects.html), 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 PingGateway route. They cannot be used by `admin.json`. If you provide a `config.json`, the PingGateway configuration is loaded from that file. If there is no file, the default configuration is loaded. ## Routes endpoint The endpoint is defined by the presence and content of `config.json`, as follows: * When `config.json` isn't 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 PingGateway 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` isn't the same object. * `BaseUriDecorator` A decorator to override the scheme, host, and port of the existing request URI. The default BaseUriDecorator is named `baseURI`. Learn more in [BaseUriDecorator](BaseUriDecorator.html). - `AuditService` Records no audit events. The default AuditService is `NoOpAuditService`. Learn more from [NoOpAuditService](NoOpAuditService.html). - `CaptureDecorator` Captures requests and response messages. The default CaptureDecorator is named `capture`, and uses the default settings given in [CaptureDecorator](CaptureDecorator.html). 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 aren't 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. Learn more from [ClientHandler](ClientHandler.html). - `ForgeRockClientHandler` Sends transaction IDs when communicating with protected applications. The default [ForgeRockClientHandler](ForgeRockClientHandler.html) is a [Chain](Chain.html), composed of a [TransactionIdOutboundFilter](TransactionIdOutboundFilter.html) and a [ClientHandler](ClientHandler.html). - `IssuerRepository` (deprecated) A repository of Issuers declared in the heap. To overwrite the default issuer, configure a local IssuerRepository with the name `IssuerRepository`. To create a new IssuerRepository containing a subset of Issuers, configure a local IssuerRepository with a different name. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The [IssuerRepository (deprecated)](IssuerRepository.html) is deprecated. For issuers known in advance, add their settings to the [ClientRegistration](ClientRegistration.html). For discovery, configure an [AuthorizationCodeOAuth2ClientFilter](AuthorizationCodeOAuth2ClientFilter.html) `"discoveryHandler"`. | - `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](ReverseProxyHandler.html). - `ScheduledExecutorService` Specifies the number of threads in a pool. - `TemporaryStorage` Manages temporary buffers. For more information, refer to [TemporaryStorage](TemporaryStorage.html). - `TimerDecorator` Records time spent within filters and handlers. The default TimerDecorator is named `timer`. For more information, refer to [TimerDecorator](TimerDecorator.html). - `TracingDecorator` Pushes traces to an [OpenTelemetry](https://opentelemetry.io/) service. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This feature has [Evolving](https://docs.pingidentity.com/pinggateway/release-notes/stability.html#interface-stability) interface stability. It is subject to change without notice, even in a minor or maintenance release. | Use this to decorate the following: * [PingGateway access token resolvers](AccessTokenResolvers.html) * [AmService](AmService.html) * [AuditService](AuditService.html) * [PingGateway filters](Filters.html) * [PingGateway handlers](Handlers.html) The default [TracingDecorator](TracingDecorator.html) is named `tracing`. PingGateway traces include Vert.x traces where applicable. - `TransactionIdOutboundFilter` Inserts the ID of a transaction into the header of a request. ## Usage | | | | - | -------------------------------------------------------------------------------- | | | Restart PingGateway after making configuration changes to load the new settings. | ```json { "handler": Handler reference, "heap": [ object, ... ], "properties": object, "session": AsyncSessionManager reference, "temporaryStorage": TemporaryStorage reference } ``` ## Properties * `"handler"`: *Handler [reference](preface.html#definition-reference), required* The [Handler](Handlers.html) to which PingGateway 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](heap-objects.html). * `"properties"`: *[object](preface.html#definition-object), optional* Configuration parameters declared as property variables for use in the configuration. Learn more in [PingGateway route properties](Properties.html). Default: No properties are defined. * `"session"`: *AsyncSessionManager [reference](preface.html#definition-reference), optional* An [InMemorySessionManager](InMemorySessionManager.html) or [JwtSessionManager](JwtSessionManager.html). Default: [InMemorySessionManager](InMemorySessionManager.html) with default values Learn more in [PingGateway sessions](../about/about-sessions.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 object defined in the heap or an inline TemporaryStorage configuration object. Incoming requests use the temporary storage buffer as follows: * Only used when `streamingEnabled` is `false`. * The request is loaded into the PingGateway storage defined in `temporaryStorage` before it enters the chain. * If the content length of the request is more than the buffer limit, PingGateway returns an `HTTP 413 Payload Too Large`. Default: Use the heap object named `TemporaryStorage`. Otherwise, use an internally created TemporaryStorage object named `TemporaryStorage` with default settings for a TemporaryStorage object. ## Example configuration files ### Default configuration When your configuration doesn't include a `config.json` file, PingGateway uses this configuration: ```json { "heap": [ { "name": "_router", "type": "Router", "config": { "scanInterval": "&{ig.router.scan.interval|10 seconds}", "directory": "${openig.configDirectory}/routes", "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" } ``` Source: [default-config.json](../_attachments/others/default-config.json) Notice the following features of the default configuration: * The handler contains a main router named `_router`. When PingGateway 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 PingGateway welcome page, PingGateway dispatches the request. Otherwise, PingGateway returns an HTTP status 404 (Resource not found), because the requested resource doesn't exist. ### Example config.json used in the documentation Many examples in the documentation use the following example `config.json` file: ```json { "handler": { "type": "Router", "name": "_router", "config": { "directory": "${openig.configDirectory}/routes" } }, "heap": [ { "name": "capture", "type": "CaptureDecorator", "config": { "captureEntity": true, "_captureContext": true } }, { "name": "ClientTlsOptions", "type": "ClientTlsOptions", "config": { "trustManager": { "type": "SecretsTrustManager", "config": { "certificateVerificationSecretId": "sampleapp.cert", "secretsProvider": { "type": "FileSystemSecretStore", "config": { "directory": "&{ig.instance.dir}/tls", "format": "PLAIN", "suffix": ".pem", "mappings": [ { "secretId": "sampleapp.cert", "format": { "type": "PemPropertyFormat" } } ] } } } } } }, { "name": "ReverseProxyHandler", "type": "ReverseProxyHandler", "config": { "tls": "ClientTlsOptions" } } ], "session": { "type": "JwtSessionManager" } } ``` Source: [config.json](../_attachments/config/config.json) Notice the following features of this configuration: * The handler defines a main router named `_router`. This `_router` routes each incoming request to the first route whose `condition` the request satisfies. * The `capture` decorator serves to capture HTTP request and response bodies. * The `ReverseProxyHandler` has TLS settings to trust the sample application self-signed certificate. * The `session` configuration uses JWT-based sessions. Learn more in [PingGateway sessions](../about/about-sessions.html). ## More information [org.forgerock.openig.http.GatewayHttpApplication](../_attachments/apidocs/org/forgerock/openig/http/GatewayHttpApplication.html)