Merge pull request #298 from kinde-oss/Feat/subscopes

Feat/subscopes

Author: marcosmartini

src/content/docs/developer-tools/kinde-api/about-m2m-scopes.mdx

@@ -14,22 +14,39 @@ app_context:
     s: apis
 ---
 
-The Kinde management API uses JSON Web Tokens (JWTs) to authenticate requests. The token’s scopes claim indicates which endpoints can be accessed when calling the management API.
+The Kinde management API uses JSON Web Tokens (JWTs) to authenticate requests. The token’s scopes claim indicates which endpoints can be accessed when calling the API.
 
 ## Example scopes
 
 - `read:users` for fetching user details.
 - `write:users` for modifying user details.
 - `read:roles` or `write:roles` for managing roles.
 
-You can select scopes when you authorize a new application or you can add scopes to an existing application. We recommend adding as few scopes as you need, to maintain API security. 
+You can select scopes when you authorize a new application or you can add scopes to an existing application. We recommend adding as few scopes as you need, to maintain API security.
 
-## Change or add scopes to an application accessing the Kinde Management API
+## Request scopes in the body of an access token request
+
+By default token requests for an authorized application will return all the scopes enabled below. You can also optionally ask for a subset of enabled scopes to be returned by including them in the body of the access token request. You might do this to add more security to access requests, or because you want your users to be very specific about scopes in their requests.
+
+Example request
+
+```
+curl --request POST \
+  --url 'https://<your_subdomain>.kinde.com/oauth2/token' \
+  --header 'content-type: application/x-www-form-urlencoded' \
+  --data grant_type=client_credentials \
+  --data 'client_id=<your_m2m_client_id>' \
+  --data 'client_secret=<your_m2m_client_secret>' \
+  --data 'audience=https://<your_subdomain>.kinde.com/api'\
+  --data 'scope=read:users update:users'
+```
+
+## Add or modify scopes for accessing the Kinde Management API
 
 Follow this procedure if you already have an application and you experience a scope error, if you want to add scopes for an application, or remove scopes to tighten security.
 
 1. Go to **Settings > Applications** and select the relevant M2M application.
 2. On the left, select **APIs**.
 3. Select the three dots next to the Kinde management API, then choose **Manage scopes**. 
 4. Select the scopes you want to include in the token. For maximum security only enable the minimum scopes you require. 
-5. Select **Save**. The scopes will now be included in the token. You do not need to also send them in the token request.
+5. Select **Save**.

src/content/docs/developer-tools/your-apis/custom-api-scopes.mdx

@@ -68,3 +68,20 @@ Take care deleting scopes. If a scope is in use, it can cause breaking changes f
 4. Select the dots menu (far right) and select:
    - **Edit scope.** You can only change the scope description. Select **Save**.
    - **Delete scope**. Confirm that you want to delete and select **Delete scope**.
+
+## Request a subset of scopes for an authorized application
+
+By default token requests for an authorized application will return all the scopes enabled in the section above. However, you can also optionally ask for a subset of enabled scopes to be returned by including them in the body of the access token request. You might do this to add more security to access requests for your API, or because you want your users to be very specific in their requests.
+
+Example request
+
+```
+curl --request POST \
+  --url 'https://<your_subdomain>.kinde.com/oauth2/token' \
+  --header 'content-type: application/x-www-form-urlencoded' \
+  --data grant_type=client_credentials \
+  --data 'client_id=<your_m2m_client_id>' \
+  --data 'client_secret=<your_m2m_client_secret>' \
+  --data 'audience=<your_api_audience>\
+  --data 'scope=join:competitions update:competitions'
+```

src/content/docs/developer-tools/your-apis/test-token-from-kinde.mdx

@@ -1,6 +1,6 @@
 ---
 page_id: be39d3bb-a83d-4d21-8941-8f1c8363c3bb
-title: Get a user access token to test your APIs (Fast method)
+title: Get a M2M token to test your APIs
 sidebar:
   order: 2
 relatedArticles:
@@ -10,7 +10,7 @@ relatedArticles:
 
 Kinde lets you quickly generate a test token for testing your APIs with Kinde. This can save you time generating a token via Postman or other service.
 
-This process assumes you have [registered](/developer-tools/your-apis/register-manage-apis/) your API with Kinde, and have [authorized an application](/developer-tools/your-apis/register-manage-apis/#authorize-or-revoke-authorization-of-an-app-from-the-api) to access it. 
+This process assumes you have [registered](/developer-tools/your-apis/register-manage-apis/) your API with Kinde, and have [authorized an M2M application](/developer-tools/your-apis/register-manage-apis/#authorize-or-revoke-authorization-of-an-app-from-the-api) to access it. 
 
 1. In Kinde, go to **Settings > APIs**.
 2. Select **View details** on your API.