> ## 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 金鑰、設定到期日，並在請求中傳送金鑰。

除 `GET /openapi.json` 外，所有端點都需要有效的 API 金鑰。金鑰的範圍**限定於機構（organization-scoped）**——
金鑰只能存取核發它的機構所屬的資料，並以機構身份而非個別教練身份操作。

## 建立金鑰

API 金鑰由**主教練或機構管理員**在 Coach Console 的 **Settings → Security** 下管理。

<Steps>
  <Step title="開啟 Settings → Security">
    在[網頁主控台](https://app.nexrex.ai)中，前往 **Settings → Security** 並找到 **API keys** 區塊。
  </Step>

  <Step title="命名金鑰並選擇存取範圍">
    為金鑰指定一個描述性名稱（例如「Analytics dashboard」），並選擇你的整合所需的
    [存取範圍（Scopes）](/zh-Hant/api-reference/scopes)。預設為唯讀。
  </Step>

  <Step title="設定到期日">
    選擇到期時間窗口——預設為 **90 天**。允許永不到期的金鑰，但不建議使用。
  </Step>

  <Step title="只有一次機會複製密鑰">
    完整金鑰（`nrx_prod_…`）僅在建立時**顯示一次**。請立即複製至你的密鑰儲存庫——
    日後無法再次查看。
  </Step>
</Steps>

<Warning>
  請像對待密碼一樣保管 API 金鑰。將其儲存在密鑰管理工具中，切勿放入版本控制或用戶端程式碼。
  若金鑰外洩，請在 **Settings → Security** 撤銷該金鑰並重新核發一組新金鑰。
</Warning>

## 傳送金鑰

支援兩種方式。建議使用 **Bearer**。

<CodeGroup>
  ```bash Bearer (recommended) theme={null}
  curl https://api.nexrex.ai/api/v1/developer/v1/org \
    -H "Authorization: Bearer nrx_prod_your_key_here"
  ```

  ```bash X-API-Key header theme={null}
  curl https://api.nexrex.ai/api/v1/developer/v1/org \
    -H "X-API-Key: nrx_prod_your_key_here"
  ```
</CodeGroup>

## 到期與撤銷

* **到期**在每次請求時強制執行。使用已到期金鑰的請求會收到 `401` 及代碼 `key_expired`——
  你的整合可藉此偵測原因，提示取得新金鑰，而非靜默失敗。
* **撤銷**立即生效。被撤銷的金鑰會收到 `401` 及代碼 `key_revoked`。
* 未知或格式錯誤的金鑰會收到 `401` 及代碼 `invalid_key`。

完整的錯誤信封與代碼列表請見[錯誤](/zh-Hant/api-reference/errors)。

## 金鑰輪替

系統不提供自動輪替。手動輪替步驟：建立新金鑰，部署後確認流量已切換
（主控台會顯示每個金鑰的**最後使用**時間），再撤銷舊金鑰。