diff --git a/docs/admin/oauth-apps.mdx b/docs/admin/oauth-apps.mdx
index b5cc061da..0b5e3998f 100644
--- a/docs/admin/oauth-apps.mdx
+++ b/docs/admin/oauth-apps.mdx
@@ -11,6 +11,23 @@ This makes OAuth the preferred choice for any multi-user integration like browse
OAuth Apps are in compliance with standards including [RFC 6749](https://tools.ietf.org/html/rfc6749), [RFC 7636 (PKCE)](https://tools.ietf.org/html/rfc7636), and [RFC 8628 (Device Authorization Grant)](https://tools.ietf.org/html/rfc8628).
+
+ OAuth Apps and service-account M2M credentials both use Sourcegraph's OAuth
+ server, but they are different client types for different jobs:
+
+ - OAuth Apps created in **Site admin > OAuth clients** are for apps acting on
+ behalf of a user. They support `authorization_code` and
+ `refresh_token`, and public clients also support the device authorization
+ flow.
+ - Service-account M2M credentials are separate OAuth clients that are bound to
+ a service account. They are the only clients that support
+ `grant_type=client_credentials`.
+
+ If your OpenID Connect discovery document lists `client_credentials`, that
+ means the Sourcegraph OAuth server supports that grant overall. It does not
+ mean every OAuth client created in the UI can use it.
+
+
Consider using **M2M (client-credentials) service-account tokens** or traditional [access tokens](/cli/how-tos/creating-an-access-token) for server-to-server communication, automated scripts, CI/CD pipelines, or single-user applications that do not require per-user permission checks. See [service accounts](/admin/service-accounts#m2m-oauth-credentials-client-credentials-flow) for details.
## Creating an OAuth App
@@ -61,7 +78,7 @@ Public clients:
Private clients can securely store client secrets:
- **Server-side web applications**
-- **Backend services**
+- **Backend services that act on behalf of signed-in users**
- **Secure server environments**
Private clients:
@@ -69,6 +86,7 @@ Private clients:
- Receive both client ID and client secret
- Can use the standard authorization code flow (PKCE strongly recommended)
- Allow client authentication with a secret and server-side code exchange
+- Still act on behalf of a user, not as a standalone machine identity
## Available Scopes
@@ -103,6 +121,10 @@ When creating an OAuth app, select the minimum scopes necessary for your applica
## OAuth Flow Examples
+The first three flows below are for OAuth Apps created in **Site admin > OAuth
+clients**. The `client_credentials` example is included for completeness, but
+it only works with M2M credentials created for a service account.
+
1. **Authorization Request**: Redirect users to Sourcegraph's authorization endpoint:
@@ -260,7 +282,7 @@ curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \
-The client credentials flow is designed for server-to-server authentication without user interaction. Service accounts can create M2M (machine-to-machine) credentials that use this flow. You can create M2M credentials in the service account settings under **Access tokens > M2M credentials**.
+The client credentials flow is designed for server-to-server authentication without user interaction. It is not available for OAuth Apps created in **Site admin > OAuth clients**. Instead, service accounts create separate M2M (machine-to-machine) credentials that use this flow. You can create M2M credentials in the service account settings under **Access tokens > M2M credentials**.
1. **Token Request** (no user interaction required):
diff --git a/docs/admin/service-accounts.mdx b/docs/admin/service-accounts.mdx
index 022a2188f..c5625b599 100644
--- a/docs/admin/service-accounts.mdx
+++ b/docs/admin/service-accounts.mdx
@@ -26,6 +26,14 @@ You'll be presented with some next steps you might want to take, like creating a
Service accounts can authenticate using either traditional access tokens or M2M (machine-to-machine) OAuth credentials.
+
+ M2M credentials are not the same thing as OAuth Apps created in
+ **Site admin > OAuth clients**. OAuth Apps are for flows where an application
+ acts on behalf of a user. M2M credentials are separate OAuth clients that are
+ bound to a service account and are the only way to use
+ `grant_type=client_credentials`.
+
+
### Traditional Access Tokens
For detailed information about creating, managing, and using traditional access tokens, see:
@@ -36,7 +44,11 @@ For detailed information about creating, managing, and using traditional access
### M2M OAuth Credentials (Client Credentials Flow)
-M2M credentials provide short-lived tokens via the OAuth client credentials flow expiring after 1 hour.
+M2M credentials provide short-lived tokens via the OAuth client credentials flow expiring after 1 hour. Tokens issued by this flow represent the service account itself, not an end-user session.
+
+If your instance's OpenID Connect discovery document lists `client_credentials`
+in `grant_types_supported`, that means the Sourcegraph OAuth server supports
+that grant globally. It does not mean a regular OAuth App can use it.
**Creating M2M credentials:**
@@ -65,7 +77,7 @@ curl -H "Authorization: Bearer ACCESS_TOKEN" \
https://sourcegraph.example.com/.api/graphql
```
-See [OAuth Apps → Client Credentials Flow](/admin/oauth-apps#oauth-flow-examples) for more details on the client credentials flow.
+See [OAuth Apps](/admin/oauth-apps#oauth-flow-examples) for a side-by-side explanation of user-delegated OAuth flows versus service-account M2M credentials.
Both authentication methods can be used to access Sourcegraph's [GraphQL API](/api/graphql) and [Stream API](/api/stream-api).