---
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: 2024.11
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-02T11:29:35Z
keywords: ["Configuration", "Microgateway", "OAuth 2.0"]
superseded_by: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/microgateway-protect-service.html
---

# 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 start, download and run the sample application as described in [Use the sample application](../getting-started/start-sampleapp.html). 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

   * Windows

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

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

   ```json
   {
     "properties": {
       "introspectOAuth2Endpoint": "http://mstokval.example.com:9090"
     },
     "capture": "all",
     "name": "mgw",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(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"
       }
     }
   }
   ```

   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 `http://app.example.com:8081`.

   * 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`:

      ```bash
      $ 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:

      ```bash
      $ echo $mytoken
      ```

   3. Call PingGateway to access microservice A:

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

      The home page of the sample application is displayed.