From f8dcb961c94606678926d4e82781db7cb7f3bb97 Mon Sep 17 00:00:00 2001
From: Xiaoyan Rao <270668624@qq.com>
Date: Wed, 10 Apr 2024 09:33:01 +0800
Subject: [PATCH] docs(plugins): updates the description for app-reg

---
 .../application-registration/how-to/_index.md | 61 ++++++++++++++++++-
 .../overview/_index.md                        |  3 +
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/app/_hub/kong-inc/application-registration/how-to/_index.md b/app/_hub/kong-inc/application-registration/how-to/_index.md
index 77c6692189b2..dbdd6c209fa4 100644
--- a/app/_hub/kong-inc/application-registration/how-to/_index.md
+++ b/app/_hub/kong-inc/application-registration/how-to/_index.md
@@ -22,7 +22,7 @@ Replace `<service>` with your service name or ID, and `<my_service_display_name>
 `display_name` of your service:
 
 ```
-curl -X POST http://localhost:8001/services/<service> \
+curl -X POST http://localhost:8001/services/<service>/plugins \
     --data "name=application-registration"  \
     --data "config.display_name=<my_service_display_name>" \
     --data "config.auto_approve=true
@@ -36,6 +36,65 @@ curl -X PATCH http://localhost:8001/plugins/<plugin_id> \
   --data "config.auto_approve=true"
 ```
 
+### Allow accessing the service with consumer credentials (optional)
+
+By enabling the Application Registration plugin on a service, access to the service with consumer credentials is disallowed by default. To allow this behavior, you can set `enable_proxy_with_consumer_credential` to `true`.
+
+{:.important}
+> **Important:** Always use `enable_proxy_with_consumer_credential` with caution, as this allows accessing the scoped service via consumer credentials other than your application's client ID (API key).
+
+```sh
+curl -X POST http://localhost:8001/services/<service>/plugins \
+    --data "name=application-registration"  \
+    --data "config.display_name=<my_service_display_name>" \
+    --data "config.enable_proxy_with_consumer_credential=true"
+```
+
+Or, update your current configuration with a `PATCH` request.
+Replace `<plugin_id>` with the `id` from the existing application-registration instance:
+
+```sh
+curl -X PATCH http://localhost:8001/plugins/<plugin_id> \
+  --data "config.enable_proxy_with_consumer_credential=true"
+```
+
+And then, create a plugin `key-auth` and route for the service.
+
+```sh
+curl -X POST http://localhost:8001/services/<service>/routes \
+    --data "path=/test"
+```
+
+```sh
+curl -X POST http://localhost:8001/services/<service>/plugins \
+    --data "name=key-auth" \
+    --data "config.key_names=apikey"
+```
+
+Create a consumer and a consumer's credential for the `key-auth`.
+
+```sh
+curl -X POST http://localhost:8001/consumers \
+    --data "username=test"
+```
+
+```sh
+curl -X POST http://localhost:8001/consumers/<consumer_id>/key-auth \
+    --data "key:<apikey>"
+```
+
+When `enable_proxy_with_consumer_credential` is enabled, constructing a request to the service should yield a 200 response, rather than the 401 response when disabled:
+
+```sh
+curl http://localhost:8000/test?apikey=<apikey>
+```
+
+The route should still be accessible with the `client_id` of the application.
+
+```sh
+curl http://localhost:8000/test?apikey=<client_id>
+```
+
 ### Enable show issuer URL
 
 Enable `show_issuer` to expose the **Issuer URL** in the **Service Details** dialog.
diff --git a/app/_hub/kong-inc/application-registration/overview/_index.md b/app/_hub/kong-inc/application-registration/overview/_index.md
index 877102a32eea..504123fca0b7 100644
--- a/app/_hub/kong-inc/application-registration/overview/_index.md
+++ b/app/_hub/kong-inc/application-registration/overview/_index.md
@@ -7,6 +7,9 @@ authenticate against a Gateway service. Dev Portal admins can
 selectively admit access to services using the
 Application Registration plugin.
 
+{:.note}
+> **Note**: By enabling the Application Registration plugin on a service, access to the service with consumer credentials is disallowed by default. To allow this behavior, check [how-to guide for allowing access to the service](/hub/kong-inc/application-registration/how-to/#allow-accessing-the-service-with-consumer-credentials-optional) for advanced configuration.
+
 {:.note}
 > **Note**: This plugin is for application registration in _self-managed_ 
 > {{site.base_gateway}} instances.