Merge pull request #476 from kinde-oss/Claire/M2M-new-section-review

Claire/new section review
- Updated procedures
- Updated headings for better AI / indexing
- Cross referenced existing topics

Author: clairekinde11

src/content/docs/build/tokens/token-customization.mdx

@@ -4,8 +4,10 @@ title: Token customization
 sidebar:
   order: 5
 relatedArticles:
+  - 7c283a32-96ec-4639-a902-ea1f4252d213
   - d8069575-dfef-421d-8f3a-8f3efe9ad2f3
   - 5a248c6f-c1ae-480a-95c3-d3c69c81598d
+  - 3a16e08b-62c7-4725-8884-7065bfb2dbf2
 app_context:
   - m: application_details
     s: tokens
@@ -45,7 +47,7 @@ You can:
 
 ### Add claims to M2M tokens
 
-You can add feature flags to an M2M token.
+You can [add feature flags to an M2M token](/machine-to-machine-applications/m2m-application-setup/add-feature-flags-to-m2m-applications/).
 
 ## Add properties to tokens
 
@@ -55,6 +57,25 @@ Properties are custom fields and information that you can attach to your users,
 
 To make a property available in a token, you need to [make the property public](/properties/work-with-properties/manage-properties/), and then customize the token following the procedure above, to add a property. 
 
+The value will appear in the token under a `application_properties` claim:
+
+```json
+{
+  "application_properties": {
+    "region": {
+      "v": "eu"
+    },
+    "tier": {
+      "v": "pro"
+    }
+  }
+}
+```
+
+The `v` is a shortcode for the value of the property.
+
+Only the properties you explicitly toggle on will be included.
+
 ## Token integration for third parties
 
 Currently, we only support formatting for Hasura.

src/content/docs/machine-to-machine-applications/about-m2m/authenticate-with-m2m.mdx

@@ -15,16 +15,14 @@ You can use a Machine-to-Machine (M2M) application in Kinde to request access to
 
 Before an M2M app can request a token for a specific API audience, it must be authorized for that API.
 
-You can do this in the Kinde dashboard:
-
-1. Go to the M2M application
-2. Select **APIs**
-3. Choose which APIs this app is allowed to call
-4. Select **Save**
+If the app is not authorized for the given audience, the token request will fail.
 
-You can also authorize apps programmatically using the Kinde Management API.
+1. Open the M2M application in Kinde.
+2. Select **APIs**.
+3. Select the three dots menu and authorize each API the app is allowed to call.
+4. Select **Save**.
 
-If the app is not authorized for the given audience, the token request will fail.
+You can also [authorize apps programmatically](https://docs.kinde.com/kinde-apis/management/#tag/apis/patch/api/v1/apis/{api_id}/applications) using the Kinde Management API.
 
 ## Get an access token
 
@@ -96,22 +94,22 @@ curl https://your-subdomain.kinde.com/api/v1/organizations \
   -H "Authorization: Bearer <token>"
 ```
 
-## Notes
+## Important information about tokens, audience, claims, and M2M apps
 
 - Access tokens are valid for 1 hour by default.
 - The `audience` must match the intended API — tokens are only valid for the audience they’re issued for.
 - You can request multiple audiences
 - If your M2M app is scoped to an organization, the token will include the `org_code` trusted claim.
 - Tokens are JWTs and can be decoded to inspect claims using standard libraries or tools like [Kinde's JWT decoder](https://kinde.com/tools/online-jwt-decoder/).
 
-## Test your M2M app from the Kinde dashboard
+## Test your M2M app in Kinde
 
-You can also generate a token from the UI:
+You can also generate a token to help with testing. 
 
-1. Go to your M2M app in Kinde
-2. Select the **Test** tab
-3. Choose the API you want to test against
-4. Select **Generate token**
-5. Copy the access token and use it in your API requests
+1. Open your M2M app in Kinde.
+2. Select *APIs* in the menu, then open the API you want to test with the app.
+3. Select the **Test** tab
+4. Select **Get token**
+5. Copy the access token and use it in your API requests.
 
 This is useful for debugging or verifying scopes and claims without writing code.

src/content/docs/machine-to-machine-applications/about-m2m/index.mdx

@@ -7,13 +7,14 @@ relatedArticles:
   - 4cb63554-d6b3-45cf-bdad-2fac4790d3aa
   - 961dea3c-d8e2-47a0-8ab7-deabdb2d6a01
   - 65d72460-e870-4d6a-a1ea-35740ca0e2cc
+  - 9f832d29-1b76-4bb2-b4dc-e4a9a9c327b3
 ---
 
 Machine-to-machine (M2M) applications allow you to authenticate backend services, scripts, or automation tools that need to call your APIs without a user being involved.
 
 M2M apps in Kinde use the OAuth 2.0 client credentials flow to obtain access tokens. These tokens can then be used to securely interact with Kinde APIs or your own APIs.
 
-You can create M2M applications for general use across your business, or scope them to a specific organization for tighter access control.
+You can create M2M applications for general use across your business, or [scope them to a specific organization](/machine-to-machine-applications/organization-scoped-m2m-apps/m2m-applications-for-organizations/) for tighter access control.
 
 ## Use cases
 
@@ -36,11 +37,16 @@ These are tied to a single organization. Tokens issued to these apps include tru
 
 ## How M2M authentication works
 
-1. Create an M2M app in the Kinde dashboard
-2. Use the provided `client_id` and `client_secret` in a client credentials request
-3. Receive an access token in response
-4. Use the token to call Kinde APIs or your own backend
+1. Create an M2M app in Kinde.
+2. Use the provided `client_id` and `client_secret` in a client credentials request.
+3. Receive an access token in response.
+4. Use the token to call Kinde APIs or your own backend.
 
 Tokens can include scopes to limit access and, if scoped to an org, will include the `org_code` trusted claim.
 
+## Best practices for M2M apps
 
+- Use separate M2M apps for different scopes or services.
+- Limit the [scopes](https://docs.kinde.com/developer-tools/your-apis/custom-api-scopes/) assigned to each M2M app to the minimum required for its function.
+- [Rotate client secrets](/build/applications/rotate-client-secret/) periodically using the UI.
+- Avoid including any personally identifiable information (PII) in token claims.

src/content/docs/machine-to-machine-applications/about-m2m/m2m-quick-start-guide.mdx

@@ -11,54 +11,57 @@ relatedArticles:
 
 This guide shows you how to create a Machine-to-Machine (M2M) application in Kinde, authorize it for an API, and use the client credentials flow to get a token and make a secure API request.
 
-## Step 1 - Create a machine-to-machine app
+## Step 1: Create a machine-to-machine app
 
-1. Go to the **Applications** section in your Kinde dashboard
-2. Select **Machine-to-machine apps**
-3. Choose **Add M2M application**
-4. Enter a name
+1. Go to the **Applications** section on the Kinde homepage and select **Add application**.
+2. In the window that opens, enter a name for the application. 
+3. Select **Machine-to-machine (M2M)**.
+4. Select **Save**.
 
-## Step 2 - Create an API in Kinde (if you don't have one)
+## Step 2: Create an API in Kinde (if you don't have one)
 
 You can skip this step if you already have an API registered in Kinde.
 
-1. Go to the **APIs** section in your Kinde dashboard
+1. Go to **Settings > Environment > APIs**.
 2. Select **Add API**
-3. Enter a name
-4. Select **Save**
+3. Enter a **Name** and **Audience**.
+4. Select **Save**.
 
-For more detail, see [Register and manage APIs](/developer-tools/your-apis/register-manage-apis/).
+For more information, see [Register and manage APIs](/developer-tools/your-apis/register-manage-apis/).
 
-## Step 3 - Authorize the app to access an API
+## Step 3: Authorize the app to access an API
 
-1. Open your newly created app
-2. Go to the **APIs** tab
-3. Select the API (audience) this app should be allowed to call.
-4. Select **Save**.
+You need to authorize the API or else token requests will be rejected.
 
-If you skip this step, token requests will be rejected.
+1. Open your newly created app.
+2. Select **APIs** in the side menu.
+3. Find the API to authorize, and select the three dots menu on the right.
+4. Select **Authorize**.
 
-## Step 4 - (Optional) Add scopes
+## Step 4: Add scopes (optional)
 
-If your API uses scopes to define permissions:
+Complete this step if your API uses scopes to define permissions.
 
-1. Go to **APIs** in your Kinde dashboard
-2. Choose the API you’re protecting
-3. Add scopes (e.g. `read:users`, `write:flags`)
-4. Go back to your M2M app and assign those scopes
+1. Go to **Settings > Environment > APIs**.
+2. Choose the API you’re protecting.
+3. Select **Scopes** from the menu.
+4. Select **Add scope** and enter a scope name and description, then select **Save**.
+5. Repeat for each scope you want to add, e.g. `read:users`, `write:flags`. 
+6. Go back to your M2M app and assign those scopes.
 
-For more detail, see [Define and manage API scopes](/developer-tools/your-apis/api-scopes-m2m-applications/).
+For more information about how to assign scopes to an API, see [Define and manage API scopes](/developer-tools/your-apis/api-scopes-m2m-applications/).
 
-## Step 5 - Get a token
+## Step 5: Get a token
 
 You can test the app in one of two ways:
 
 ### Option A - Use the Test tab in Kinde
 
-1. Open your M2M app
-2. Go to the **Test** tab
-3. Select the API (audience)
-4. Copy the generated token
+1. Open your M2M app.
+2. Select **APIs** in the menu and then open the API you want to test.
+3. Select **Test** in the menu.
+4. Select the Authorized application and then **Get token**.
+5. Copy the generated token.
 
 ### Option B - Use the client credentials flow directly
 
@@ -82,7 +85,7 @@ The response will include a bearer token you can use in requests:
 }
 ```
 
-## Step 6 - Use the token in an API call
+## Step 6: Use the token in an API call
 
 Include the token in the `Authorization` header:
 

src/content/docs/machine-to-machine-applications/about-m2m/token-structure-and-claims-for-m2m-applications.mdx

@@ -13,13 +13,13 @@ Access tokens issued by Kinde to Machine-to-Machine (M2M) applications are JSON
 
 This reference explains what those claims are and how to use them securely in your APIs or services.
 
-## How to view token claims
+## How to view M2M token claims
 
 Tokens returned from the client credentials flow can be decoded using any standard JWT library, or online tools like [Kinde's JWT decoder](https://kinde.com/tools/online-jwt-decoder/).
 
 You do **not** need to validate the signature unless you're verifying tokens on your own backend (outside of Kinde-hosted APIs). For most use cases, Kinde validates the token for you when you call our APIs.
 
-## Example token payloads
+## Example M2M token payloads
 
 ### Global M2M app
 
@@ -70,7 +70,7 @@ You do **not** need to validate the signature unless you're verifying tokens on
 }
 ```
 
-## Standard claims
+## Standard M2M token claims
 
 | Claim | Description |
 |-------|-------------|
@@ -85,23 +85,22 @@ You do **not** need to validate the signature unless you're verifying tokens on
 | `scp` | The list of scopes initially requested |
 | `v` | The version of the token. |
 
-## Additional claims for org-scoped apps
+## Additional M2M claims for org-scoped apps
 
 | Claim | Description |
 |-------|-------------|
 | `org_code` | The organization code for the token. |
 
 
-
-## Validating and using claims
+## Validating and using claims for M2M apps
 
 In your API or backend service, you can use these claims to enforce access:
 
 - Confirm the `aud` matches the expected audience for your API
 - If your endpoint is organization-specific (e.g. `/orgs/:org_code/...`), ensure that `org_code` from the token matches the route parameter
 - Use `scopes` to implement scope-based access control (e.g. `write:flags` required to enable a feature flag)
 
-## Notes
+## Important information about M2M tokens, audiences, and scopes
 
 - Tokens are signed using asymmetric keys (RS256)
 - You can retrieve your Kinde environment’s public keys from the [OpenID configuration endpoint](https://your-subdomain.kinde.com/.well-known/openid-configuration)

src/content/docs/machine-to-machine-applications/m2m-application-setup/add-feature-flags-to-m2m-applications.mdx

@@ -11,26 +11,31 @@ relatedArticles:
 
 You can include feature flags in the tokens issued to machine-to-machine (M2M) applications in Kinde. This is helpful for enabling or disabling functionality in downstream systems based on feature access.
 
-> **Note:** At this time, only **environment-level feature flags** can be included in M2M tokens. Support for organization-assigned flag values may be added in future releases.
+<Aside>
+
+At this time, only **environment-level feature flags** can be included in M2M tokens. Support for organization-assigned flag values may be added in future releases.
+
+</Aside>
 
 ## Define environment-level feature flags
 
-Before including a flag in a token, you need to define it in your environment.
+Before including a flag in a token, you need to define it in your environment. This is the quick procedure (below), here's the [detailed procedure for adding feature flags](/releases/feature-flags/add-feature-flag/). 
 
-1. In Kinde, go to **Releases**
-2. Select **Add flag**
-3. Give the flag a key and (optionally) description
-4. Choose the flag type (boolean, string, number)
-5. Add a default value (optional)
-6. Select **Save**
+1. In Kinde, go to **Releases**.
+2. Select **Add feature flag**.
+3. Give the flag a key and (optionally) a description.
+4. Choose the flag type (boolean, string, integer, JSON).
+5. (Optional) Add a default value.
+6. (Optional) Decide if the feature flag value can be overridden.
+7. Select **Save**.
 
 Once defined, this flag will be available for inclusion in any M2M token issued in the same environment.
 
 ## Include a flag in an M2M token
 
-1. Go to **Applications > Your M2M app**
-2. Select the **Tokens** tab
-3. Under **Feature flags**, toggle on the flags you want included in the token
+1. Go to **Settings > Applications > Your M2M app**.
+2. Select **Tokens** in the menu.
+3. Under **Feature flags**, toggle on the flags you want included in the token.
 
 These flags will be embedded in the token under the `feature_flags` claim: