feat: flesh out M2M section of docs

Author: DaveOrDead

src/content/docs/build/organizations/organization-m2m-applications.mdx

@@ -1,90 +1,21 @@
 ---
-page_id: bbcccc7e-2a7a-44f2-8069-1c4bd37141b1
-title: Machine-to-Machine (M2M) access scoped to organizations
+page_id: 44a1ac1e-3e17-44e1-b503-2e0e678f5cc2
+title: Give API access to an organization using M2M
 sidebar:
-  order: 10
+  order: 8
 relatedArticles:
-  - 815f10b0-7bd2-407a-9ac2-9fb582862a5b
-  - 8f6af95a-14ef-436d-862f-bfa82e836558
-  - 263176d3-d823-4bba-a95f-02f6df00bd10
+  - 9f832d29-1b76-4bb2-b4dc-e4a9a9c327b3
+  - d2c841f1-78b4-47e0-b899-4d32ae857e0a
 ---
 
-<Aside type="upgrade">
+If you want to give automated systems, AI agents, or backend services access to data in a specific organization, you can do this securely using an **organization-scoped machine-to-machine (M2M) application**.
 
-This is an advanced feature that is only available on the [Kinde Plus or Scale plans](https://kinde.com/pricing/)
+This type of app is tied to a single organization and can only be used to access resources for that org.
 
-</Aside>
+To create an org-scoped M2M app:
 
-Kinde supports creating machine-to-machine (M2M) applications that are scoped to a specific organization. This lets you securely issue access tokens tied to an organization, ensuring that any automation or service calling your APIs is restricted to the correct customer context.
+1. In Kinde, go to **Organizations**, then select the organization.
+2. Select **Machine-to-machine apps**.
+3. Follow the steps to create the app and assign the appropriate scopes.
 
-Global (unscoped) M2M applications are still supported for broader use cases, such as internal automation across multiple orgs.
-
-## When to use an org-scoped M2M application
-
-You should use an organization-scoped M2M app when:
-
-- You are building automation that acts on behalf of a specific customer or tenant.
-- You are deploying AI agents, bots, or backend services that must be restricted to a single organization’s data.
-- You want to issue different tokens with separate scopes or permissions per organization.
-- You need to simplify tenant isolation and avoid passing or validating org codes manually.
-
-## How it works
-
-1. Create an M2M application inside an organization in the Kinde dashboard.
-2. Assign scopes that define what the app can access (e.g. `read:users`, `write:flags`).
-3. Use the client credentials flow to request an access token using the generated `client_id` and `client_secret`.
-4. Kinde returns a token with trusted claims about the organization and app.
-5. The token can be used to interact with Kinde APIs on behalf of that organization.
-
-Each org-scoped app is tightly bound to a single organization. Tokens issued from that app cannot be used across orgs.
-
-## Token structure
-
-An example tokens issued to an org-scoped M2M app may include the following claims:
-
-```json
-{
-  "aud": ["https://api.foobar.com/v1/"],
-  "azp": "12ce25d1109d4c66b0f469e47d33f8eb",
-  "exp": 1751212288,
-  "gty": ["client_credentials"],
-  "iat": 1751125888,
-  "iss": "https://example.kinde.com",
-  "jti": "28a8d6a8-fe7c-4c90-84a6-1b3ccaaeabf2",
-  "org_code": "org_1234567890",
-  "scope": "read:users write:flags",
-  "scp": ["read:users", "write:flags"],
-  "v": "2"
-}
-```
-
-These claims can be used by your backend services to authorize access to specific APIs or resources.
-
-## Org-scoped vs global M2M applications
-
-| Feature               | Global M2M app                     | Org-scoped M2M app             |
-| --------------------- | ---------------------------------- | ------------------------------ |
-| Org context in token  | No                                 | Yes                            |
-| Tenant data isolation | Manual                             | Enforced                       |
-| Use case              | Admin scripts, internal automation | Per-tenant agents, scoped APIs |
-| Token restrictions    | None                               | Scoped to one org              |
-| Token claims          | Basic                              | Includes `org_code`, `scope`   |
-
-## Create an org-scoped M2M app
-
-1. In Kinde, go to **Organizations**, then view an organization.
-2. Select **M2M apps**.
-3. Select **Add M2M application**
-4. Enter a name for the application
-5. Select **Save**.
-
-Kinde generates a `client_id` and `client_secret` tied to the selected organization.
-Use the credentials in a standard client credentials flow to request a token.
-
-## Best practices
-
-- 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](https://docs.kinde.com/build/applications/rotate-client-secret/) periodically using the UI.
-- Audit token usage by tracking `client_id` and `org_code` in logs.
-- Avoid including any personally identifiable information (PII) in token claims.
+For full details, see [M2M access scoped to organizations](/machine-to-machine-applications/m2m-applications-for-organizations/).

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

@@ -0,0 +1,69 @@
+---
+page_id: 524fa2a5-62b1-4c78-8786-b5aa9d7dc1ff
+title: Assign feature flags for use in M2M tokens
+sidebar:
+  order: 7
+relatedArticles:
+  - 3a16e08b-62c7-4725-8884-7065bfb2dbf2
+  - 5b13e167-b032-4a61-a67a-81a12d6e20d5
+  - f1c72f80-4f8e-4b5e-bc4d-6f2a798ec7f1
+---
+
+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.
+
+## Define environment-level feature flags
+
+Before including a flag in a token, you need to define it in your environment.
+
+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**
+
+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
+
+These flags will be embedded in the token under the `feature_flags` claim:
+
+```json
+{
+  "feature_flags": {
+      "new-ai-agent": {
+          "t": "b",
+          "v": true
+       },
+  	   "access-level": {
+          "t": "s",
+          "v": "beta"
+       }
+    }
+}
+```
+The `t` and `v` are short codes for the type and value of the feature flag.
+
+- `t` = `type` (boolean, string, number)
+- `v` = `value` (true | false, "beta", 1, etc.)
+
+Only the feature flags you explicitly toggle on will be included.
+
+## Common use cases
+
+- Enable or disable AI models or endpoints
+- Drive conditional logic in APIs or job runners
+- Gate functionality in distributed workers
+
+## Notes
+
+- Flags are set at the **environment** level — they are global, not org-specific
+- Token customization is configured per-app in the **Tokens** tab
+- Tokens remain small: only enabled flags are included
+- Flag values are read-only for the recipient — you must update them via the dashboard or API

src/content/docs/machine-to-machine-applications/add-metadata-to-an-m2m-application-with-properties.mdx

@@ -0,0 +1,64 @@
+---
+page_id: 6f82d354-7b77-4560-99d7-20a5b723b4b3
+title: Add metadata to an M2M application using properties
+sidebar:
+  order: 6
+relatedArticles:
+  - 3a16e08b-62c7-4725-8884-7065bfb2dbf2
+  - 5b13e167-b032-4a61-a67a-81a12d6e20d5
+  - 9f832d29-1b76-4bb2-b4dc-e4a9a9c327b3
+---
+
+You can use **Properties** in Kinde to add structured metadata to a machine-to-machine (M2M) application. These properties can store configuration or contextual data like `region`, `tier`, or `model_version`.
+
+This is useful for:
+- Customizing tokens
+- Driving logic in downstream systems
+- Managing AI agent behavior
+
+If you're looking to include properties inside tokens, see [Customize the contents of an M2M token](/build/applications/m2m-customize-token/).
+
+## Step 1 — Define your property
+
+Before you can assign a property to an app, you need to define it.
+
+1. In Kinde, go to **Properties**
+2. Select **Add property**
+3. Choose the object type: **Application**
+4. Give the property a name (e.g. `tier`, `region`, `model_version`)
+5. Add a description and data type (optional)
+6. You can opt for whether a property is allowed to be included in tokens (optional)
+7. Select **Save**
+
+Once saved, this property is now available across all M2M applications.
+
+## Step 2 — Assign the property to an M2M application
+
+1. In Kinde, go to **Applications > M2M apps**
+2. Select the app you want to assign metadata to
+3. Open the **Properties** tab
+4. Add or edit values for the available fields
+
+For example:
+
+| Property        | Value     |
+|----------------|-----------|
+| region          | eu        |
+| model_version   | v2        |
+| tier            | pro       |
+
+These values are stored with the app but are not included in tokens unless explicitly enabled.
+
+## Next: Use properties as token claims
+
+If you want to include these properties inside tokens issued to the app:
+
+→ See [Customize the contents of an M2M token](/build/applications/m2m-customize-token/)
+
+There, you can toggle which properties are included in the token under the `custom` claim.
+
+## Notes
+
+- Properties are available for applications, users, and organizations
+- Only **Application** properties are relevant for M2M apps
+- This feature is useful for setting up per-customer configuration without hardcoding or external storage

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

@@ -0,0 +1,116 @@
+---
+page_id: f1c72f80-4f8e-4b5e-bc4d-6f2a798ec7f1
+title: Authenticate with Machine-to-Machine (M2M) Applications
+sidebar:
+  order: 3
+relatedArticles:
+  - d2c841f1-78b4-47e0-b899-4d32ae857e0a
+  - 9f832d29-1b76-4bb2-b4dc-e4a9a9c327b3
+  - 90134c89-16e4-4981-b988-b0cb4f1722c5
+---
+
+You can use a machine-to-machine (M2M) application in Kinde to request access tokens using the OAuth 2.0 client credentials flow. These tokens can be used to call Kinde’s APIs or your own APIs with no user interaction required.
+
+## Authorize your application
+Before a machine-to-machine (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**
+
+You can also authorize apps programmatically using the Kinde Management API.
+
+If the app is not authorized for the given audience, the token request will fail.
+
+## Get an access token
+
+Your M2M application will be provided with a `client_id` and `client_secret` which can be used to request a token.
+
+To get a token, make a `POST` request to your Kinde environment’s token endpoint:
+
+```http
+POST https://<your-subdomain>.kinde.com/oauth2/token
+```
+
+### Required parameters
+
+The request body must include:
+
+```text
+grant_type=client_credentials
+&client_id=<your-client-id>
+&client_secret=<your-client-secret>
+&audience=<your-api-audience>
+```
+
+If your app has scopes assigned, you can optionally request them:
+
+```text
+&scope=read:users write:flags
+```
+
+**Note**: The `audience` parameter tells Kinde which API the token is intended for. Use `https://<your-subdomain>.kinde.com/api/v1` when calling Kinde’s management API. If you're protecting your own custom API, the audience should match the identifier you registered for that API in Kinde.
+
+### Example (cURL)
+
+```bash
+curl --request POST 'https://your-subdomain.kinde.com/oauth2/token' \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data-urlencode 'grant_type=client_credentials' \
+  --data-urlencode 'client_id=your-client-id' \
+  --data-urlencode 'client_secret=your-client-secret' \
+  --data-urlencode 'audience=your-api-audience' \
+  --data-urlencode 'scope=read:users write:flags'
+```
+
+### Successful response
+
+A successful request returns a JSON response with an access token:
+
+```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+## Use the token
+
+Once you have a token, include it as a Bearer token in the `Authorization` header when making API calls:
+
+```http
+Authorization: Bearer <token>
+```
+
+## Example usage
+
+Calling a Kinde API:
+
+```bash
+curl https://your-subdomain.kinde.com/v1/organizations \
+  -H "Authorization: Bearer <token>"
+```
+
+## Notes
+
+- 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
+
+You can also generate a token from the UI:
+
+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
+
+This is useful for debugging or verifying scopes and claims without writing code.