Skip to content

docs: improve auth methods docs and make clear different types of auth available #1754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
enriquegh merged 1 commit into from
Sep 16, 2026
+31 −0
Merged

docs: improve auth methods docs and make clear different types of auth available #1754

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/admin/service-accounts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,19 @@

Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password, cannot access the Sourcegraph UI, don't count towards a license's user limit and won't be part of any billing cycles.

## Choosing an authentication method

Choose a method based on whose permissions the integration should use and whether it supports OAuth:

| Method | Best for | Identity used for requests | Token behavior |
| ------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------- |
| Service account with M2M credentials | CI/CD and server-to-server integrations that support OAuth client credentials | A dedicated machine identity | Uses `grant_type=client_credentials` to issue one-hour tokens |
| Service account with an access token | Automation that does not support OAuth client credentials | A dedicated machine identity | Uses a traditional Sourcegraph access token with the configured expiration policy |
| OAuth App | Multi-user applications acting on behalf of signed-in users | Each signed-in user | Issues one-hour access tokens and rotating refresh tokens |
| User access token | CLI usage, quick tests, and one-off scripts | The user who created the token | Uses a traditional Sourcegraph access token with the configured expiration policy |

If your integration should act as one non-human identity, use a service account. Prefer M2M credentials when the integration supports OAuth client credentials. If it should act on behalf of each signed-in user, use an [OAuth App](/admin/oauth-apps). For a simple token tied to one identity, use an [access token](/cli/how-tos/creating-an-access-token).

## Creating Service Accounts

Service accounts are created like regular user accounts, but with a few key differences.
Expand Down
12 changes: 12 additions & 0 deletions docs/api/mcp/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,3 +93,15 @@ Authorization: token YOUR_ACCESS_TOKEN
```

Access tokens can use the `mcp` scope to restrict access to MCP endpoints only.

## Troubleshooting

Most MCP connection issues come from OAuth or access-control configuration rather than the MCP endpoint itself.

| If you see | Likely cause | What to check |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_scope` during OAuth sign-in | The OAuth client requested a scope it is not configured to use | For MCP-only connections, request the `mcp` scope. DCR clients cannot request general API scopes such as `user:all`. For an integration that also needs GraphQL access, create a pre-registered [OAuth App](/admin/oauth-apps) configured with both `mcp` and `user:all`. |
| `redirect_uri_mismatch` or a token exchange failure after browser authorization | The OAuth client is missing the callback URL expected by the MCP client | Register the exact redirect URI your client uses. For the `mcp-remote` configuration above, add `http://localhost:3334/oauth/callback` to the OAuth App. |
| `/.auth/idp/oauth/register` returns `404 not found` | Dynamic Client Registration is disabled | Confirm `mcp.enabled` and `auth.idpDynamicClientRegistrationEnabled` are both `true`. To keep MCP available without DCR, use a pre-registered OAuth client instead. |
| Users must sign in again frequently after the integration previously worked | The client is not refreshing tokens correctly | OAuth access tokens expire after one hour. Store the newest `refresh_token` returned by each refresh because refresh tokens are one-time use. M2M flows do not return refresh tokens; request a new access token when the current one expires. |
| `403 forbidden` from `/.api/mcp` | The token lacks the `mcp` scope or the user lacks MCP access | Confirm the OAuth client is configured with `mcp` and the user has the `MCP#ACCESS` permission. If MCP is disabled, the endpoint returns `404` instead. |
6 changes: 6 additions & 0 deletions docs/cli/how-tos/managing-access-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@ The `auth.accessTokens` setting in Sourcegraph's site configuration allows admin
}
```

<Callout type="note">
`auth.accessTokens` only controls Sourcegraph access tokens. It does not
disable [OAuth Apps](/admin/oauth-apps), service-account M2M credentials, or
MCP Dynamic Client Registration.
</Callout>

## Access token creation

The `allow` property permits or restricts the use of access tokens. It can be assigned one of three values:
Expand Down
Loading