> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonce.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证与访问权限

> 了解 API 凭据，以及工作区和矿场的访问权限。

访问工作区数据需要认证。Public API v2 接受工作区 API key 或 OAuth access token，两者使用相同的请求头：

```http theme={null}
Authorization: Bearer <credential>
```

[Get Bitcoin Metrics](/api-reference/v2/bitcoin/get-bitcoin-metrics) 可匿名访问，无需携带此请求头。

## 工作区 API key

API key 适用于服务端应用、脚本和服务。在 [Nonce 应用](https://nonce.app) 中选择工作区，打开 **Manage**，再选择 **API Keys**。该入口对具有 `workspace.manage` 权限的用户可见；没有此权限的开发者可联系工作区管理员获取密钥。

工作区 API key 代表其所属工作区，在该工作区内拥有管理员权限，不受运行脚本的开发者个人角色限制。密钥应保存在服务端环境变量或密钥管理服务中，避免写入浏览器代码、代码仓库或日志。

## OAuth

OAuth 请求代表已认证的用户，其访问权限取决于工作区成员身份、角色及分配的矿场范围。[MCP 客户端](/zh/api-guide/mcp)通过 Nonce 连接流程获取并管理 OAuth 凭据。

## 资源访问

操作权限决定允许执行哪些动作，矿场范围决定这些动作可以作用于哪些矿场。读取矿场和 Agent 需要 `farm.read`；读取矿机和 task batch 需要 `miner.read`。

`ListWorkspaces` 返回可访问的工作区。每个工作区的 `permissions` 列出允许调用的 API 操作，`relations` 则表示成员身份（`member`）或授权访问关系（`grantee`）。可访问的矿场由 `ListFarms` 单独列出。

使用 API key 跨工作区访问时，目标工作区需要向密钥所属工作区授予有效授权。此类访问仅允许读取，并且只能访问授权范围内的矿场。

## 访问错误

| 状态码 | 含义                  |
| --- | ------------------- |
| 401 | 凭据缺失、无效或已过期         |
| 403 | 缺少所需权限、工作区成员身份或有效授权 |
| 404 | 资源不存在，或不在可访问的矿场范围内  |

错误格式见[请求与响应](/zh/api-guide/v2/requests)，角色模型见[角色与权限](/zh/user-guide/permissions/role-overview)。