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

# 存取範圍

> 七種 API 權限及舊版金鑰的對應方式。

每個 API 金鑰帶有一個或多個**存取範圍（Scopes）**。每個端點都需要特定的存取範圍，
其參考說明中會列出。請求若缺少所需範圍，會收到 `403` 及代碼 `missing_scope`——
錯誤訊息會指出缺少哪個範圍。

僅授予你的整合所需的最小範圍集合。

## 存取範圍列表

| 範圍                | 授予權限                     |
| ----------------- | ------------------------ |
| `org:read`        | 讀取機構中繼資料（名稱、運動員數量）       |
| `athletes:read`   | 列出運動員並讀取運動員個人資料          |
| `activities:read` | 讀取運動員活動資料（依隱私設定過濾——詳見下方） |
| `plans:read`      | 讀取運動員的使用中訓練計畫            |
| `groups:read`     | 讀取機構群組中繼資料               |
| `exports:create`  | 建立非同步資料匯出任務              |
| `exports:read`    | 列出、查閱及下載匯出任務             |

## 舊版別名

在範圍限定權限功能推出之前建立的金鑰帶有粗略的 `read`、`write` 或 `admin` 範圍。
這些範圍仍有效，並會自動擴展：

| 舊版範圍    | 擴展為                             |
| ------- | ------------------------------- |
| `read`  | 全部五個 `*:read` 範圍                |
| `admin` | 全部七個範圍                          |
| `write` | *（不具備 Developer API 存取權——保留用途）* |

你不需要遷移舊金鑰。建立新金鑰時，請選擇精確的範圍。

## 活動資料的隱私上限

`activities:read` 所能揭露的資料，不會超過**同一機構內的教練**對該運動員所能看到的內容。
每個活動在離開 API 之前都會經過運動員自身隱私設定的篩選：運動員選擇設為私密的欄位
（配速、地圖、心率等）會被移除，且已隱藏的活動會被完全省略。

運動員也可以在行動 App 中將**單一活動**標記為私密，這與其全域隱私設定
彼此獨立。單一活動的隱私選擇與其他隱私過濾一視同仁：該活動會從
`GET /activities` 清單結果中省略，`GET /activities/{activity_id}` 對此活動
會回傳 `404`。

<Note>
  這意味著擁有相同範圍的兩個金鑰，可能因為運動員調整隱私設定，
  在不同時間對同一運動員收到不同的資料。請以欄位可能缺席為前提開發，
  而非假設欄位形狀固定不變。
</Note>