---
title: PingGateway as a microgateway
description: Configure PingGateway as a microgateway using the Token Validation Microservice to resolve and cache OAuth 2.0 access tokens for protected APIs
component: pinggateway
version: 2026
page_id: pinggateway:gateway-guide:microgateway-protect-service
canonical_url: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/microgateway-protect-service.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: 2026-06-01T16:50:04Z
keywords: ["Configuration", "Microgateway", "OAuth 2.0"]
---

# PingGateway as a microgateway

This page describes how to use the ForgeRock Token Validation Microservice to resolve and cache OAuth 2.0 access tokens when protecting API resources. It's based on the example in *Introspecting stateful access tokens* in the Token Validation Microservice [*User guide*](https://cdn-docs.pingidentity.com/archive/pdf/tvm/1/Token-Validation-Microservice-1-User-Guide.pdf).

For information about the architecture, refer to [PingGateway as a microgateway](../about/about-microgateway.html). The following figure illustrates the flow of information when a client requests access to a protected microservice, providing a stateful access token as credentials:

![Request flow when a client requests access to a protected microservice.](_images/mgw.svg)

Before you begin, follow the instructions in [Using the sample application](../getting-started/start-sampleapp.html) to have the sample application listening at `https://app.example.com:8444` with PingGateway trusting it for HTTPS and ready to serve static resources. The sample application acts as Microservice A.

1. Set up the example in *Introspecting stateful access tokens* in the Token Validation Microservice *User guide*.

2. In AM, edit the microservice client to add a scope to access the protected microservice:

   1. Select Applications > OAuth 2.0 > Clients.

   2. Select `microservice-client`, and add the scope `microservice-A`.

3. Add the following route to PingGateway:

   * Linux

     `$HOME/.openig/config/routes/mgw.json`

   * Windows

     `%appdata%\OpenIG\config\routes\mgw.json`

   ```json
   {
     "properties": {
       "introspectOAuth2Endpoint": "http://mstokval.example.com:9090"
     },
     "capture": "all",
     "name": "mgw",
     "baseURI": "https://app.example.com:8444",
     "condition": "${find(request.uri.path, '^/home/mgw')}",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "OAuth2ResourceServerFilter-1",
             "type": "OAuth2ResourceServerFilter",
             "config": {
               "requireHttps": false,
               "accessTokenResolver": {
                 "name": "TokenIntrospectionAccessTokenResolver-1",
                 "type": "TokenIntrospectionAccessTokenResolver",
                 "config": {
                   "endpoint": "&{introspectOAuth2Endpoint}/introspect",
                   "providerHandler": "ForgeRockClientHandler"
                 }
               },
               "scopes": ["microservice-A"]
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }
   ```

   Source: [mgw.json](../_attachments/config/routes/mgw.json)

   Notice the following features of the route:

   * The route matches requests to PingGateway on `http://ig.example.com:8080/home/mgw`, and rebases them to the sample application, on `https://app.example.com:8444`.

   * The OAuth2ResourceServerFilter expects an OAuth 2.0 access token in the header of the incoming authorization request, with the scope `microservice-A`.

   * If the filter successfully validates the access token, the ReverseProxyHandler passes the request to the sample application.

4. Test the setup:

   1. With AM, PingGateway, the Token Validation Microservice, and the sample application running, get an access token from AM, using the scope `microservice-A`:

      ```console
      $ mytoken=$(curl -s \
      --request POST \
      --url http://am.example.com:8088/openam/oauth2/access_token \
      --user microservice-client:password \
      --data grant_type=client_credentials \
      --data scope=microservice-A --silent | jq -r .access_token)
      ```

   2. View the access token:

      ```console
      $ echo $mytoken
      ```

   3. Call PingGateway to access microservice A:

      ```console
      $ curl -v --header "Authorization: Bearer ${mytoken}" http://ig.example.com:8080/home/mgw
      ```

      The sample application returns its home page HTML.