Docs updates for JWT OATs (#2905)

Co-authored-by: Sarah Soutoul <sarah@clerk.dev>
Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>

Author: 3 people

docs/_tooltips/oauth-access-token.mdx

@@ -1 +1 @@
-An **OAuth access token** is a randomly generated string or JSON Web Token (JWT) that is given to the [client](!oauth-client) by the **authorization service** if the OAuth process is completed successfully. The client can then send this token to the **resource service** to be allowed to access the relevant resources and data. Learn more about how [OAuth access tokens work](/docs/guides/configure/auth-strategies/oauth/overview).
+An **OAuth access token** is a credential issued by an authorization server that grants the [client](!oauth-client) access to protected resources on behalf of a user. Access tokens represent the authorization granted to the client and are typically short-lived for security purposes. Learn more about [how OAuth works](/docs/guides/configure/auth-strategies/oauth/overview).

docs/_tooltips/opaque-token.mdx

@@ -1 +1 @@
-An **opaque token** is a type of access token that is not human-readable and cannot be easily inspected or decoded. It is used to authenticate requests to a protected resource. Opaque tokens are normally verified with a network call to the issuer rather than a digital signature verification, and can be revoked immediately -- both properties that are different from JWTs.
+An **opaque token** is a type of access token that is not human-readable and cannot be easily inspected or decoded. It is used to authenticate requests to a protected resource. Learn more about [opaque tokens](/docs/guides/development/machine-auth/token-formats#opaque-tokens).

docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx

@@ -91,6 +91,16 @@ The consent screen is enabled by default for all OAuth apps. You can enable or d
 - Authorization codes expire **after 10 minutes**.
 - OIDC `id_token`s expire **after 1 day**.
 
+## Access token format
+
+Clerk issues OAuth access tokens as [JSON Web Tokens (JWTs)](/docs/guides/how-clerk-works/tokens-and-signatures#json-web-tokens-jwts) by default. JWTs are self-contained tokens that can be verified without making a network request to Clerk's servers.
+
+If your use case requires instant token revocation, you can configure your OAuth application to issue [opaque tokens](!opaque-token) instead. Unlike JWTs, opaque tokens require a network request to Clerk for verification, but can be revoked immediately.
+
+To configure the token format for an OAuth application, navigate to the [**OAuth applications**](https://dashboard.clerk.com/~/oauth-applications) page in the Clerk Dashboard and select the "Settings" tab, then toggle the **Generate access tokens as JWTs** switch on or off depending on your needs.
+
+For a detailed comparison of JWT and opaque token formats, including trade-offs and when to use each, see [Token formats](/docs/guides/development/machine-auth/token-formats).
+
 ## Authorization server metadata
 
 An important feature of modern OAuth 2.0 and OpenID Connect (OIDC) implementations is **authorization server metadata**. This is a standardized JSON document published by the authorization server that describes its configuration, supported features and endpoints. This metadata makes it easier for clients to automatically discover important endpoints and features without needing manual configuration.

docs/guides/configure/auth-strategies/oauth/overview.mdx

@@ -38,7 +38,7 @@ Before diving deeper, it's essential to understand some common terminology aroun
 - **Client**: The application requesting access to a user's data/resources. For example, in the earlier scenario, Content Planner acts as the **client**, since it needs permission to make posts from Twitter, Facebook, LinkedIn, etc.
 - **Authorization service (or Identity Provider, IdP)**: The service responsible for authenticating the user and granting third-party apps access to a user's account, based on user consent. For instance, Twitter's auth service manages this process for apps wanting to access Twitter resources. This is also known as an **authorization server** or **Identity Provider (IdP)**.
 - **Resource service (or Service Provider, SP)**: The service that holds the data that the [client](!oauth-client) wants to access. Following the same example, Twitter's API would be the resource service. This is sometimes referred to as a **resource server** or **Service Provider (SP)**.
-- **OAuth access token**: A randomly generated string or JSON Web Token (JWT) that is given to the [client](!oauth-client) by the **authorization service** if the OAuth process is completed successfully. The client can then send this token to the [resource service](!oauth-resource-service) to be allowed to access the relevant resources and data.
+- **OAuth access token**: A credential issued to the [client](!oauth-client) by the **authorization service** after successful authentication and user consent. The client presents this token to the [resource service](!oauth-resource-service) to access protected resources on behalf of the user. Access tokens are typically short-lived and can be refreshed using a refresh token.
 - **Scopes**: Permissions that define which specific actions or data a [client](!oauth-client) can access on the [resource service](!oauth-resource-service) on behalf of the user. For example, a **scope** might allow readings emails but not sending them. Scopes are requested by the client during the OAuth flow and are displayed to the user, usually via a consent screen.
 
 ## OAuth flow overview

docs/guides/configure/auth-strategies/oauth/verify-oauth-tokens.mdx

@@ -7,7 +7,9 @@ If you are building an application that uses Clerk and would like to incorporate
 
 <Include src="_partials/machine-token-pricing-callout" />
 
-Clerk's SDKs support this through the `acceptsToken` parameter that can be used in Clerk's route protection functions, such as [`auth()`](/docs/reference/nextjs/app-router/auth), [`auth.protect()`](/docs/reference/nextjs/app-router/auth#auth-protect), and [`authenticateRequest()`](/docs/reference/backend/authenticate-request).
+Clerk's SDKs support this through the `acceptsToken` parameter that can be used in Clerk's route protection functions, such as [`auth()`](/docs/reference/nextjs/app-router/auth), [`auth.protect()`](/docs/reference/nextjs/app-router/auth#auth-protect), and [`authenticateRequest()`](/docs/reference/backend/authenticate-request). The SDKs automatically handle verification for both [JWT and opaque token formats](/docs/guides/development/machine-auth/token-formats) - no code changes are required regardless of which format you've configured.
+
+If you need to verify JWT-formatted OAuth tokens outside of Clerk's SDKs, you can use the same approach as [manual JWT verification](/docs/guides/sessions/manual-jwt-verification) using your instance's public key.
 
 For examples and best practices on verifying OAuth tokens with Clerk SDKs, see our framework-specific guides for:
 

docs/guides/development/machine-auth/token-formats.mdx

@@ -0,0 +1,34 @@
+---
+title: Token formats
+description: Learn about the differences between JWT and opaque token formats for machine authentication.
+---
+
+When configuring machine tokens in Clerk (such as OAuth access tokens), you can choose between two token formats: **JWT** and **opaque**. Each format has trade-offs that make it better suited for different use cases.
+
+## JWT tokens
+
+[JSON Web Tokens (JWTs)](/docs/guides/how-clerk-works/tokens-and-signatures#json-web-tokens-jwts) are self-contained tokens that encode claims (such as user ID, scopes, and expiration) directly within the token. JWTs are signed using your instance's private key and can be verified using the corresponding public key.
+
+### Benefits
+
+- **Networkless verification**: JWTs can be verified locally using your instance's [public key](/docs/guides/sessions/manual-jwt-verification#get-your-instances-public-key), without making a network request to Clerk's servers.
+- **Self-contained**: All necessary information is embedded in the token itself.
+- **Performance**: Reduces latency by eliminating round-trip network requests for verification.
+
+### Limitations
+
+- **Cannot be instantly revoked**: Once issued, a JWT remains valid until it expires. Revocation requires waiting for the token to expire or implementing additional revocation logic.
+
+## Opaque tokens
+
+Opaque tokens are randomly generated strings that contain no embedded information. They must be verified by making a request to Clerk's servers, which looks up the token in a database, and is then able to retrieve associated information about the token.
+
+### Benefits
+
+- **Instant revocation**: Opaque tokens can be revoked immediately, making them ideal for security-sensitive applications where you need to invalidate access quickly.
+
+### Limitations
+
+- **Network dependency**: Every verification requires a network request to Clerk's servers.
+- **Latency**: Verification is slower due to the network round-trip.
+- **Compatibility**: There are certain third-party tools and libraries that only support JWT tokens.

docs/manifest.json

@@ -992,6 +992,10 @@
                           "title": "Using API keys",
                           "href": "/docs/guides/development/machine-auth/api-keys",
                           "tag": "(Beta)"
+                        },
+                        {
+                          "title": "Token formats",
+                          "href": "/docs/guides/development/machine-auth/token-formats"
                         }
                       ]
                     ]