Authentication and Access Control
Source Graph has five kinds of caller, and every request is treated as exactly one of them:
| Caller | How it is recognized | Can do |
|---|---|---|
| Anonymous | No Authorization header, while public reading is on | Read-only operations on repositories marked public; rate-limited |
| Signed-in user | A browser session after Google or GitHub sign-in | Read every registered repository; create personal API keys; save a personal Git credential |
| Administrator | A signed-in user with the administrator role | Everything a user can, plus registering and maintaining repositories, site settings, users and global credentials |
| Personal API key | Authorization: Bearer sgk_… | Its owner's reads over HTTP and MCP; administrator keys created with prepare permission may also request indexing over MCP |
| Service token | Authorization: Bearer <SOURCEGRAPH_API_TOKEN> | Every HTTP and MCP operation, for automation |
Any other Authorization value is rejected with 401 AUTHENTICATION_REQUIRED; an invalid credential never silently becomes anonymous access.
Set up sign-in
Source Graph signs users in with Google (OpenID Connect) or GitHub (OAuth). A provider is enabled when both its client ID and client secret are set; with neither configured, the sign-in screen explains what is missing and the site stays anonymous and read-only.
| Provider | Environment variables | Callback URL | Scopes |
|---|---|---|---|
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | <origin>/sourcegraph/auth/google/callback | openid, profile, email | |
| GitHub | GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET | <origin>/sourcegraph/auth/github/callback | read:user |
<origin> is the value of SOURCEGRAPH_ORIGIN, the public origin without a path. Register exactly that callback with the provider: for Google, create an OAuth client of type Web application and add it as an authorized redirect URI; for GitHub, create an OAuth App and use it as the authorization callback URL. Store the secrets in your platform's secret store, restart the service, and sign in. When the public origin changes — for example when the service moves behind another domain — update SOURCEGRAPH_ORIGIN and both provider callbacks together.
GitHub sign-in only identifies users; it does not grant repository access. Git credentials for private repositories are configured separately, as described in Registering Repositories.
The first administrator
Users are identified by provider and that provider's stable subject ID. Matching email addresses never merge identities or grant administrator rights, so the same person signing in with Google and with GitHub becomes two separate users.
The first verified sign-in on a new instance atomically becomes the administrator. Configure one provider, complete the owner's first sign-in, and only then add a second provider or make the site public. Administrators can promote other users on the Users page; at least one enabled administrator must always remain, and administrators cannot demote themselves.
Who may sign in
The site setting Allow other users to sign in or register is off by default. While it is off, only administrators can sign in. Anyone else is refused with a server-rendered 403 page that shows the configurable notice in both languages, links to the project and returns to the previous page after five seconds. Turning the setting off also cuts off existing non-administrator sessions, and their personal API keys are refused with REGISTRATION_CLOSED.
Anonymous reading is independent of this setting: visitors can still read repositories marked public while public reading is enabled in the site's access settings. A repository registered with public_read: false is hidden from anonymous visitors only — every admitted signed-in user can read it.
Sessions and API keys
A browser session lasts 90 days in an HTTP-only, same-site cookie scoped to /sourcegraph, marked secure on HTTPS origins. Signing in again replaces the browser's previous session.
Personal API keys are for scripts and Agents acting as you. Create them in your user settings with a name and an optional expiry; each key starts with sgk_ and can be copied later from the same page. Keys stop working when they expire, when you delete them, when your account is disabled, or when registration is closed and you are not an administrator.
Personal keys are read-only over HTTP. Over MCP they get the read-only tools, unless an administrator created the key with Prepare index permission — then the prepare tool is also available, limited to 10 requests per minute per key and 60 per minute in total. The permission is re-checked on every request, so it lapses if the owner stops being an administrator.
The service token, set with SOURCEGRAPH_API_TOKEN and at least 32 characters long, is compared in constant time and grants full access. Treat it like a root credential and keep it out of shared configuration.
Access errors
| Code | Status | Meaning |
|---|---|---|
AUTHENTICATION_REQUIRED | 401 | No usable credential, or an invalid, expired or disabled one |
ACCESS_DENIED | 403 | The credential is valid but not allowed here — for example a personal key on a management route |
ADMIN_REQUIRED | 403 | A non-administrator tried to create a key with prepare permission |
REGISTRATION_CLOSED | 403 | Sign-in is restricted to administrators |
PREPARATION_NOT_ALLOWED | 403 | Anonymous callers can never request indexing |
RATE_LIMITED | 429 | An anonymous or prepare rate limit was reached; retry after the Retry-After interval |
登录与准入
Source Graph 有五类调用方，每个请求都会被认定为其中恰好一类：
| 调用方 | 识别方式 | 可执行的操作 |
|---|---|---|
| 匿名访客 | 开启公开阅读时，请求不带 Authorization 头 | 对标记为公开的仓库执行只读操作；受限流约束 |
| 已登录用户 | 通过 Google 或 GitHub 登录后的浏览器会话 | 读取所有已登记的仓库；创建个人 API Key；保存个人 Git 凭据 |
| 管理员 | 拥有管理员角色的已登录用户 | 拥有普通用户的全部权限，另可登记和维护仓库，管理站点设置、用户和全局凭据 |
| 个人 API Key | Authorization: Bearer sgk_… | 以其所有者身份通过 HTTP 和 MCP 读取；管理员创建且带 prepare 权限的 Key 还可通过 MCP 请求建索引 |
| 服务令牌 | Authorization: Bearer <SOURCEGRAPH_API_TOKEN> | 可执行所有 HTTP 和 MCP 操作，供自动化使用 |
其他任何 Authorization 值都会被拒绝并返回 401 AUTHENTICATION_REQUIRED；无效凭据绝不会悄悄降级为匿名访问。
配置登录
Source Graph 支持通过 Google（OpenID Connect）或 GitHub（OAuth）登录。某个登录提供方只有在客户端 ID 和客户端密钥都已设置时才会启用；如果两者都未配置，登录页会说明缺少什么，站点保持匿名只读状态。
| 提供方 | 环境变量 | 回调 URL | 授权范围 |
|---|---|---|---|
GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET | <origin>/sourcegraph/auth/google/callback | openid、profile、email | |
| GitHub | GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET | <origin>/sourcegraph/auth/github/callback | read:user |
<origin> 是 SOURCEGRAPH_ORIGIN 的值，即不含路径的公开源地址。请在提供方处登记完全一致的回调地址：在 Google 中创建类型为 Web application 的 OAuth 客户端，并将其添加为已授权的重定向 URI；在 GitHub 中创建 OAuth App，并将其用作授权回调 URL。把密钥存入你所用平台的密钥存储，重启服务后即可登录。当公开源地址变化时（例如服务迁移到另一个域名之后），请同时更新 SOURCEGRAPH_ORIGIN 和两个提供方的回调地址。
GitHub 登录只用于识别用户，并不授予仓库访问权限。私有仓库的 Git 凭据需要另行配置，详见 登记仓库。
首位管理员
用户通过登录提供方及该提供方下稳定的主体 ID 来识别。邮箱地址相同既不会合并身份，也不会授予管理员权限，因此同一个人分别用 Google 和 GitHub 登录，会成为两个独立的用户。
新实例上第一次通过验证的登录会以原子方式成为管理员。请先只配置一个提供方，完成所有者的首次登录，之后再添加第二个提供方或将站点设为公开。管理员可以在 Users 页面提升其他用户；系统中必须始终保留至少一名启用状态的管理员，且管理员不能降低自己的权限。
谁可以登录
站点设置 Allow other users to sign in or register（允许其他用户登录或注册）默认关闭。关闭期间只有管理员可以登录。其他人会被拒绝，并看到服务端渲染的 403 页面：页面以两种语言显示可配置的提示，附有项目链接，并在五秒后返回上一页。关闭该设置还会切断现有非管理员用户的会话，他们的个人 API Key 也会被拒绝并返回 REGISTRATION_CLOSED。
匿名阅读与该设置相互独立：只要站点的访问设置中开启了公开阅读，访客仍可读取标记为公开的仓库。以 public_read: false 登记的仓库只对匿名访客隐藏——所有被准入的已登录用户都能读取它。
会话与 API Key
浏览器会话有效期为 90 天，保存在作用域为 /sourcegraph 的 HTTP-only、same-site Cookie 中，在 HTTPS 源上会标记为 secure。再次登录会替换该浏览器之前的会话。
个人 API Key 供以你的身份运行的脚本和 Agent 使用。在用户设置中创建 Key 时需填写名称，可选设置过期时间；每个 Key 都以 sgk_ 开头，之后也可以在同一页面再次复制。Key 在以下情况会失效：到期、被你删除、你的账号被停用，或注册已关闭且你不是管理员。
个人 Key 在 HTTP 上是只读的。在 MCP 上它只能使用只读工具，除非是管理员创建且带有 Prepare index 权限的 Key——这时还可以使用 prepare 工具，限流为每个 Key 每分钟 10 次、总计每分钟 60 次。该权限会在每次请求时重新校验，因此一旦所有者不再是管理员，权限即失效。
服务令牌通过 SOURCEGRAPH_API_TOKEN 设置，长度至少 32 个字符，以恒定时间比较，并授予完全访问权限。请像对待 root 凭据一样对待它，不要放进共享配置中。
访问错误
| 错误码 | 状态码 | 含义 |
|---|---|---|
AUTHENTICATION_REQUIRED | 401 | 没有可用凭据，或凭据无效、已过期、已停用 |
ACCESS_DENIED | 403 | 凭据有效但无权访问此处——例如用个人 Key 访问管理路由 |
ADMIN_REQUIRED | 403 | 非管理员尝试创建带 prepare 权限的 Key |
REGISTRATION_CLOSED | 403 | 登录仅限管理员 |
PREPARATION_NOT_ALLOWED | 403 | 匿名调用方永远不能请求建索引 |
RATE_LIMITED | 429 | 触发了匿名限流或 prepare 限流；请在 Retry-After 指定的间隔后重试 |