Merge pull request #466 from kinde-oss/feat/m2m-for-organizations

Do not Merge: M2M orgs doc

Author: DaveOrDead

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

@@ -0,0 +1,21 @@
+---
+page_id: 44a1ac1e-3e17-44e1-b503-2e0e678f5cc2
+title: Give API access to an organization using M2M
+sidebar:
+  order: 8
+relatedArticles:
+  - 9f832d29-1b76-4bb2-b4dc-e4a9a9c327b3
+  - d2c841f1-78b4-47e0-b899-4d32ae857e0a
+---
+
+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 type of app is tied to a single organization and can only be used to access resources for that org.
+
+To create an org-scoped M2M app:
+
+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.
+
+For full details, see [M2M access scoped to organizations](/machine-to-machine-applications/organization-scoped-m2m-apps/m2m-applications-for-organizations/).

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

@@ -0,0 +1,117 @@
+---
+page_id: 961dea3c-d8e2-47a0-8ab7-deabdb2d6a01
+title: Authenticate with M2M applications
+sidebar:
+  order: 3
+relatedArticles:
+  - d2c841f1-78b4-47e0-b899-4d32ae857e0a
+  - 4cb63554-d6b3-45cf-bdad-2fac4790d3aa
+  - 65d72460-e870-4d6a-a1ea-35740ca0e2cc
+---
+
+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 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**
+
+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/api/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.

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

@@ -0,0 +1,46 @@
+---
+page_id: d2c841f1-78b4-47e0-b899-4d32ae857e0a
+title: M2M overview
+sidebar:
+  order: 1
+relatedArticles:
+  - 4cb63554-d6b3-45cf-bdad-2fac4790d3aa
+  - 961dea3c-d8e2-47a0-8ab7-deabdb2d6a01
+  - 65d72460-e870-4d6a-a1ea-35740ca0e2cc
+---
+
+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.
+
+## Use cases
+
+Common scenarios where M2M apps are useful:
+
+- Internal automation scripts that manage users, flags, or orgs
+- CI/CD pipelines that update configuration or deploy features
+- AI agents that need to interact with your product on behalf of a customer
+- Customer-facing API keys that are tied to a specific tenant
+
+## Types of M2M apps in Kinde
+
+### Global (unscoped) M2M apps
+
+These are not linked to any one organization and can be used to call APIs across multiple orgs. Typically used for admin-level automation or infrastructure integration.
+
+### Org-scoped M2M apps
+
+These are tied to a single organization. Tokens issued to these apps include trusted claims like `org_code`, ensuring that any access is isolated to that organization’s context.
+
+## 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
+
+Tokens can include scopes to limit access and, if scoped to an org, will include the `org_code` trusted claim.
+
+

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

@@ -0,0 +1,93 @@
+---
+page_id: 4cb63554-d6b3-45cf-bdad-2fac4790d3aa
+title: Quick start
+sidebar:
+  order: 2
+relatedArticles:
+  - d2c841f1-78b4-47e0-b899-4d32ae857e0a
+  - 961dea3c-d8e2-47a0-8ab7-deabdb2d6a01
+  - 65d72460-e870-4d6a-a1ea-35740ca0e2cc
+---
+
+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
+
+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
+
+## 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
+2. Select **Add API**
+3. Enter a name
+4. Select **Save**
+
+For more detail, see [Register and manage APIs](/developer-tools/your-apis/register-manage-apis/).
+
+## 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**.
+
+If you skip this step, token requests will be rejected.
+
+## Step 4 - (Optional) Add scopes
+
+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
+
+For more detail, see [Define and manage API scopes](/developer-tools/your-apis/api-scopes-m2m-applications/).
+
+## 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
+
+### Option B - Use the client credentials flow directly
+
+```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'
+```
+
+The response will include a bearer token you can use in requests:
+
+```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+## Step 6 - Use the token in an API call
+
+Include the token in the `Authorization` header:
+
+```bash
+curl https://your-subdomain.kinde.com/v1/organizations \
+  -H "Authorization: Bearer <token>"
+```
+

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

@@ -0,0 +1,110 @@
+---
+page_id: 65d72460-e870-4d6a-a1ea-35740ca0e2cc
+title: Token structure and claims
+sidebar:
+  order: 4
+relatedArticles:
+  - 4cb63554-d6b3-45cf-bdad-2fac4790d3aa
+  - 961dea3c-d8e2-47a0-8ab7-deabdb2d6a01
+  - d2c841f1-78b4-47e0-b899-4d32ae857e0a
+---
+
+Access tokens issued by Kinde to Machine-to-Machine (M2M) applications are JSON Web Tokens (JWTs)that include trusted claims about the app, scopes, and (if applicable) the organization.
+
+This reference explains what those claims are and how to use them securely in your APIs or services.
+
+## How to view 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
+
+### Global M2M app
+
+```json
+{
+  "aud": [
+    "your-api-audience"
+  ],
+  "azp": "d4d3c5b74e064badb9625a4aa6241bcc",
+  "exp": 1751237068,
+  "gty": [
+    "client_credentials"
+  ],
+  "iat": 1751150668,
+  "iss": "https://<your-subdomain>.kinde.com",
+  "jti": "f95ed3e0-cc4d-40c4-b95a-9971729b0ae5",
+  "scope": "read:users write:flags",
+  "scp": [
+    "read:users",
+    "write:flags"
+  ],
+  "v": "2"
+}
+```
+
+### Org-scoped M2M app
+
+```json
+{
+  "aud": [
+    "your-api-audience"
+  ],
+  "azp": "d4d3c5b74e064badb9625a4aa6241bcc",
+  "exp": 1751237068,
+  "gty": [
+    "client_credentials"
+  ],
+  "iat": 1751150668,
+  "iss": "https://<your-subdomain>.kinde.com",
+  "jti": "f95ed3e0-cc4d-40c4-b95a-9971729b0ae5",
+  "org_code": "org_ba4a2311eb1",
+  "scope": "read:users write:flags",
+  "scp": [
+    "read:users",
+    "write:flags"
+  ],
+  "v": "2"
+}
+```
+
+## Standard claims
+
+| Claim | Description |
+|-------|-------------|
+| `aud` | The audience for the token. This is the API that the token is intended for. |
+| `azp` | The client ID of the M2M app that requested the token. |
+| `exp` | The expiration time of the token. |
+| `gty` | The grant type for the token. This is always `client_credentials`. |
+| `iat` | The issuance time of the token. |
+| `iss` | The issuer of the token. This is the Kinde environment URL. |
+| `jti` | The unique identifier for the token. |
+| `scope` | The scopes granted to the token. |
+| `scp` | The list of scopes initially requested |
+| `v` | The version of the token. |
+
+## Additional claims for org-scoped apps
+
+| Claim | Description |
+|-------|-------------|
+| `org_code` | The organization code for the token. |
+
+
+
+## Validating and using claims
+
+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
+
+- 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)
+- Token claims are added by Kinde based on the M2M app’s configuration and assigned scopes — they cannot be overridden in the token request
+- You can request multiple audiences
+- You can request specific scopes to limit the permissions of the token