认证与鉴权¶

大多数 AtomGit API 请求需要认证；未携带认证信息时只返回公共数据。每个接口的文档页都会明确标注是否允许匿名访问，以及该接口支持的令牌类型。

访问令牌¶

AtomGit API 统一使用 AtomGit 用户访问令牌（AtomGit user access tokens）。仓库内全部接口页的「访问令牌支持说明」都指向该类型；部分接口（如搜索、公开仓库读取）允许匿名访问，携带令牌后可以读到非公开内容。

令牌在个人访问令牌页面创建，创建时按需分配权限范围。令牌只应保存在环境变量或密钥管理系统中，不要写进仓库。

同一个令牌可以用三种方式之一传递给服务端，效果等价，按调用场景选择。

1. Authorization 请求头（推荐）

curl --location 'https://api.atomgit.com/api/v5/user' \
--header 'Authorization: Bearer {your-token}'

2. PRIVATE-TOKEN 请求头

curl --location 'https://api.atomgit.com/api/v5/user' \
--header 'PRIVATE-TOKEN: {your-token}'

3. access_token 查询参数

curl "https://api.atomgit.com/api/v5/users/{username}?access_token={your-token}"

查询参数会把令牌留在 URL 里，容易被日志、代理和历史记录带走，只建议在无法设置请求头的场景使用。

认证信息缺失或无效时，接口返回 401：

{
  "message": "401 Unauthorized"
}

令牌有效但权限不足时返回 403，例如用户无权删除该项目。