Adds docs for JWT M2M Tokens

docs/_partials/machine-auth/create-token-example.mdx

@@ -3,6 +3,15 @@ const m2mToken = await clerkClient.m2m.createToken()
 console.log(m2mToken)
 ```
 
+By default, `createToken()` creates an [opaque token](!opaque-token). To create a [JWT](!jwt-token) instead, pass `tokenFormat: 'jwt'`:
+
+```ts
+const m2mToken = await clerkClient.m2m.createToken({
+  tokenFormat: 'jwt',
+})
+console.log(m2mToken)
+```
+
 While it is strongly recommended to use environment variables for security, if you need to pass in the machine secret key directly rather than using an environment variable, you can do so by passing it as an argument to the `createToken()` method, as shown in the following example:
 
 ```ts

docs/_partials/machine-auth/jwt-token-limitation.mdx

@@ -0,0 +1,2 @@
+> [!NOTE]
+> [JWT tokens](!jwt-token) are not stored by Clerk, so they cannot be fetched via the **list** endpoint (`clerkClient.m2m.list()`). The list endpoint will only return [opaque tokens](!opaque-token). Additionally, since JWT verification happens client-side, Clerk cannot track `last_used_at` for JWT tokens.

docs/_tooltips/jwt-token.mdx

@@ -0,0 +1 @@
+A **JSON Web Token (JWT)** is a self-contained, signed token that encodes claims (such as scopes and expiration) directly within the token. JWTs can be verified locally without a network request. Learn more about [JWT tokens](/docs/guides/development/machine-auth/token-formats#jwt-tokens).

docs/guides/development/machine-auth/api-keys.mdx

@@ -129,7 +129,7 @@ The method returns an object containing the API key details, including the `secr
 - `scopes` - An array of scope strings that define what the API key can access.
 - `claims` - A JavaScript object that can be used to store additional information about the API key.
 - `createdBy` - The user ID of the user creating the API key (for audit purposes).
-- `secondsUntilExpiration` - The number of seconds until the API key expires. By default, API keys never expire. They are typically long-lived tokens since automatic expiration could cause third-party services using them to break unexpectedly. Instead, API keys can be instantly revoked if there is a security issue - this is possible because they are [opaque tokens](!opaque-token) rather than [JSON Web Tokens (JWTs)](https://en.wikipedia.org/wiki/JSON_Web_Token).
+- `secondsUntilExpiration` - The number of seconds until the API key expires. By default, API keys never expire. They are typically long-lived tokens since automatic expiration could cause third-party services using them to break unexpectedly. Instead, API keys can be instantly revoked if there is a security issue - this is possible because they are [opaque tokens](!opaque-token) rather than [JSON Web Tokens (JWTs)](!jwt-token).
 
 ### Listing API keys
 

docs/guides/development/machine-auth/m2m-tokens.mdx

@@ -28,7 +28,7 @@ Before getting started, it's important to note that M2M tokens will be a paid fe
 
 There will be usage stats and monitoring available in the Clerk Dashboard before the beta period comes to an end to make it easy to understand your usage and what you're being charged.
 
-There will also be a feature that allows the use of [JSON Web Tokens (JWTs)](https://en.wikipedia.org/wiki/JSON_Web_Token) instead of [opaque tokens](!opaque-token) before the beta period comes to an end. While JWTs can't be instantly revoked, they don't require a network request for verification and incur charges only for creation, not verification.
+M2M tokens can be created as either [opaque tokens](!opaque-token) (the default) or [JSON Web Tokens (JWTs)](!jwt-token). JWTs don't require a network request for verification and incur charges only for creation, not verification. For a detailed comparison of the two formats, see [Token formats](/docs/guides/development/machine-auth/token-formats).
 
 ## Creating machines
 
@@ -98,8 +98,9 @@ await fetch('<machine-b-url>', {
 })
 ```
 
-There are two additional optional arguments that can be passed to the `createToken()` method:
+There are additional optional arguments that can be passed to the `createToken()` method:
 
+- `tokenFormat` - The format of the token. Can be `'opaque'` (default) or `'jwt'`. See [Token formats](/docs/guides/development/machine-auth/token-formats) for more details.
 - `secondsUntilExpiration` - The number of seconds until the token will expire. By default, the token will not expire.
 - `claims` - A JavaScript object that can be used to store additional information about the token.
 
@@ -149,6 +150,8 @@ If the token is valid, the method will return an object with the following prope
 
 You can then fulfill the request, or reject it if the token is invalid.
 
+<Include src="_partials/machine-auth/jwt-token-limitation" />
+
 ## Revoking M2M tokens
 
 To revoke an M2M token, call the [`revokeToken()`](/docs/reference/backend/m2m-tokens/revoke-token) method:
@@ -161,3 +164,6 @@ await clerkClient.m2m.revokeToken({
 ```
 
 This will revoke the token and prevent it from being used to authenticate any future requests.
+
+> [!IMPORTANT]
+> Only [opaque tokens](!opaque-token) can be revoked. [JWT tokens](!jwt-token) are not stored by Clerk and therefore cannot be revoked. If you need revocation capability, use the default opaque token format when creating tokens.

docs/guides/how-clerk-works/overview.mdx

@@ -106,7 +106,7 @@ An alternative approach is "stateless" authentication, which addresses the scala
 The stateless authentication flow operates as follows. This example assumes that the user already signed up and their credentials are stored in a database.
 
 1. The user initiates authentication by navigating to `example.com/sign-in`, entering their credentials (e.g. username/password), and submitting the form, usually by clicking a "submit" button. This makes a request to the server with the credentials.
-1. The server validates the credentials against a database. Upon successful validation, it generates a [cryptographically signed token](/docs/guides/how-clerk-works/tokens-and-signatures) containing essential user data like the user ID and any relevant [claims](https://clerk.com/glossary#claim). JSON Web Tokens (JWTs) are by far the most common form of signed tokens in the modern web.
+1. The server validates the credentials against a database. Upon successful validation, it generates a [cryptographically signed token](/docs/guides/how-clerk-works/tokens-and-signatures) containing essential user data like the user ID and any relevant [claims](https://clerk.com/glossary#claim). [JSON Web Tokens (JWTs)](!jwt-token) are by far the most common form of signed tokens in the modern web.
 1. The server responds to the browser's request by sending the token in a [`Set-Cookie` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) in the response. This token serves as a self-contained proof of authentication, and will be included in future requests from the browser in order to authenticate the user.
    <Video
      src="/docs/images/how-clerk-works/stateless-auth.mp4"

docs/guides/sessions/jwt-templates.mdx

@@ -6,7 +6,7 @@ description: Learn how to create custom JWT templates to generate JSON Web Token
 > [!WARNING]
 > This guide is for creating custom JWT templates in order to generate JSON Web Tokens with Clerk. If you are looking for how to customize your Clerk-generated session token, refer to the [Customize your session token](/docs/guides/sessions/customize-session-tokens) guide.
 
-Clerk offers the ability to generate [JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWTs). Each JWT, or token, represents a user that is currently signed in to your application.
+Clerk offers the ability to generate [JSON Web Tokens](!jwt-token) (JWTs). Each JWT, or token, represents a user that is currently signed in to your application.
 
 You can control the claims that will go into these tokens by creating custom **JWT templates** that fit your needs. This enables you to integrate with any third-party services that support authentication with JWTs. An example use case is integrating with a third-party service that is able to consume JWTs, but requires them to be in a particular format.
 

docs/reference/backend/m2m-tokens/create-token.mdx

@@ -20,6 +20,11 @@ function createToken(params?: CreateM2MTokenParams): Promise<M2MToken>
 
   ---
 
+  - `tokenFormat?`
+  - `'opaque' | 'jwt'`
+
+  The format of the token. Defaults to `'opaque'`. Set to `'jwt'` to create a [JSON Web Token](/docs/guides/how-clerk-works/tokens-and-signatures#json-web-tokens-jwts) that can be verified locally without a network request. For a detailed comparison of the two formats, see [Token formats](/docs/guides/development/machine-auth/token-formats).
+
   - `secondsUntilExpiration?`
   - `number | null`
 

docs/reference/backend/m2m-tokens/list.mdx

@@ -9,8 +9,7 @@ Retrieves a list of M2M tokens for a given machine. Returns a [`PaginatedResourc
 - When fetching M2M tokens with a Machine Secret Key, only tokens associated with the authenticated machine can be retrieved.
 - When fetching M2M tokens with a Clerk Secret Key, tokens for any machine in the instance can be retrieved.
 
-> [!NOTE]
-> JWT tokens are not stored by Clerk, so they cannot be fetched via the list endpoint.
+<Include src="_partials/machine-auth/jwt-token-limitation" />
 
 ```ts
 function list(queryParams: GetM2MTokenListParams): Promise<PaginatedResourceResponse<M2MToken[]>>

docs/reference/backend/m2m-tokens/revoke-token.mdx

@@ -9,6 +9,9 @@ Revokes an [M2M token](/docs/guides/development/machine-auth/m2m-tokens). This e
 - When revoking a M2M token with a Machine Secret Key, the token must be managed by the Machine associated with the Machine Secret Key.
 - When revoking a M2M token with a Clerk Secret Key, any token on the instance can be revoked.
 
+> [!IMPORTANT]
+> Only [opaque tokens](!opaque-token) can be revoked. [JWT tokens](!jwt-token) are not stored by Clerk and therefore cannot be revoked. If you need revocation capability, use the default opaque token format when creating tokens.
+
 ```ts
 function revokeToken(params: RevokeM2MTokenParams): Promise<M2MToken>
 ```

docs/reference/backend/m2m-tokens/verify.mdx

@@ -6,6 +6,8 @@ sdk: js-backend
 
 Verifies an [M2M token](/docs/guides/development/machine-auth/m2m-tokens). Must be authenticated via a Machine Secret Key.
 
+<Include src="_partials/machine-auth/jwt-token-limitation" />
+
 ```ts
 function verify(params: VerifyM2MTokenParams): Promise<M2MToken>
 ```