【2026 最新】Alter 多使用者 Agent 權限教學：六步查清 API 替誰執行

你和同事都登入了同一個 AI 助手。你問自己的行事曆，同事查他的客戶資料；畫面明明顯示不同姓名，背後卻可能共用一把能讀取全部資料的 API 金鑰。這篇 Alter 多使用者 Agent 權限教學，要帶你追到真正發出請求的那一刻：它究竟替誰執行？

這篇寫給第一次接觸 Agent 授權、願意和開發者一起核對流程的讀者。先用白話畫出關係，再看整合骨架與六步驗收；你不必先懂密碼學，也能指出哪一層選錯了人。程式段落供已有 Python 與測試服務的開發者接線。

以下依 2026 年 10 月 23 日查閱的 Alter 官方文件、公開整合程式與 OWASP 指引整理。本站未使用 Alter 帳號執行供應商 API；後面的 A／B 情境是建議驗收規格，預期結果與實際觀察請分欄記錄。

先說結論：一次呼叫，要把人、授權與請求綁在一起

逐請求授權＝可信使用者＋Agent 身分＋有效 grant＋這次動作。把 Agent 想成跑腿同事：識別證說他是誰，委託單說他替誰辦事，櫃檯還要核對這次要領哪份資料。登入成功，只完成了其中一部分。

• 使用者身分從後端驗證過的登入流程取得，別讓模型填 user_id 決定替誰執行。
• 每個人委派自己的 grant；呼叫時同時帶入該 grant 與使用者 JWT。
• 先做 A／B 唯讀對照，再交換 grant；檢查應用、Alter 與測試後端三邊的證據。
• 需要核准的動作走 Proxy；另測改參數、撤權、重複送出及旁路，別只看聊天回覆。

一、Alter 多使用者 Agent 權限：先分清五個零件

Alter 將憑證保管、授權政策、核准與稽核接在一起。官方架構說明把 grant 定義為代表某個身分使用供應商的授權紀錄。下面這五個角色分開記，才不會把一把共用服務金鑰誤認成每個人的權限。

• ①「本人」User：提出任務的人。JWT（帶簽章的身分資料）由 IDP，也就是登入身分提供者，簽發；程式要驗證它，而非只讀出其中姓名。
• ②「跑腿者」Agent：執行工作的軟體身分，有自己的金鑰。Agent 金鑰與 Google 等供應商憑證是兩類秘密。
• ③「委託單」Grant：授權用哪個連接帳號、以什麼範圍辦事；grant_id 是它的識別碼，拿到編號仍要接受授權檢查。
• ④「鑰匙」Credential：真正讓下游 API 接受請求的 token 或 API key。它屬於哪個帳號，會影響實際讀到什麼。
• ⑤「門口」Proxy：由 Alter 後端注入憑證並呼叫供應商；政策與核准在這條執行路徑上發生。

把完整路線讀一次：A 的登入 JWT → 你的服務（Agent 金鑰）→ A 委派的 grant → Alter Proxy → A 的供應商帳號。同事 B 走相同程式，卻要解析到 B 的委託單與憑證。想補上模型與工具怎麼分工，可以先讀Agent Harness 白話教學。

二、登入的人與被讀取的物件，都要驗證

假設登入者是 A，工具參數卻寫 user_id="B"。安全設計應繼續採用已驗證的 A 身分，並拒絕不被允許的身分切換。模型產生的工具參數是待檢查資料；若把它當登入證據，就像讓跑腿者自己改委託人的姓名。

OWASP 的物件層授權指引另外提醒，每個接受物件 ID 並操作物件的 API，都應檢查當前使用者對該物件與動作的權限。只比對一個 user ID，仍不足以處理所有物件權限問題。換句話說，身分對了，訂單或文件也要對。

這篇刻意驗兩層：第一層是選到哪個人的憑證；第二層是用該憑證操作哪個資源。單一 Google 試算表權限教學著重第二層的檔案邊界；這裡先把多人共用服務的逐請求身分接對。

三、Alter 多使用者 Agent 權限六步驗收

第一步「先認門」：跑通官方唯讀入門

不知道應從哪裡開始？先走官方 Quickstart的 Google Calendar 讀取流程：建立測試 App、設定 Google、建立後端使用的金鑰，再由你有權使用的測試帳號完成同意。查閱時的需求為 Python 3.11 以上或 Node 20 以上；Python 套件名稱為 alter-sdk。已有相符 Python 的讀者，可在新的練習目錄執行：

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install alter-sdk
python -m pip show alter-sdk

先記錄實際安裝版本，再依 Quickstart 的連線與讀取程式取得結果。只放自建的假行程，例如「A 的練習會議」。金鑰放後端秘密設定，畫面、聊天和查核檔都不要收錄原文。這一步的可觀察成果是讀到正確測試行程；單一 App 成功，還沒驗完多人 Agent 的委派。

第二步「分兩張委託單」：建立 A／B 對照

怕兩個人其實用了同一把鑰匙？準備兩個自己有權管理的測試身分與各自的假資料；A 的標記為 A-only-731，B 為 B-only-842，不要互相分享。每位使用者各自完成連接與委派給同一個 Agent，再依官方多人伺服器指南，以當前 JWT 查詢該人委派的 grant。

若走 managed secret（代管 API key）路線，特別檢查 grant_kind="managed_secret" 與 access_via="ms_delegation"。官方指出，Agent 自有的 managed-secret grant 沒有終端使用者維度，查詢時仍會列出。把它誤選為 A 與 B 的答案，就又回到共用憑證。OAuth 的委派資料形狀另查 SDK 文件，不把這兩個 managed-secret 篩選條件直接套過去。

驗收時別只看兩個 grant ID 不同：兩張 grant 也可能連到同一底層帳號。你要核對的是下游回報的帳號身分，以及是否各自只讀到預期假資料。

第三步「後端選人」：把 JWT 與 grant 一起送出

擔心模型換掉身分？讓框架的驗證流程先交出 verified_jwt，再由後端查 grant。以下是針對自有 HTTPS Mock 服務的整合骨架：auth-lab 是你配置的 managed-secret provider slug；MOCK_READ_URL 固定在伺服器設定，指向只回傳假身分資料的讀取端點，不從模型參數接受目的地。

from alter_sdk import HttpMethod, PendingApproval

async def read_as_user(agent, verified_jwt, MOCK_READ_URL):
    matches, offset = [], 0
    while True:
        page = await agent.list_grants(
            end_user_token=verified_jwt, status="active", offset=offset
        )
        matches.extend(g for g in page.grants
            if g.grant_kind == "managed_secret"
            and g.access_via == "ms_delegation"
            and g.managed_secret_slug == "auth-lab")
        if not page.has_more:
            break
        if not page.grants:
            raise RuntimeError("invalid_pagination")
        offset += len(page.grants)
    if len(matches) != 1:
        raise ValueError("grant_selection_required")
    result = await agent.proxy_request(
        HttpMethod.GET, MOCK_READ_URL,
        grant_id=matches[0].grant_id, user_token=verified_jwt,
        reason="Read synthetic identity for authorization check",
    )
    if isinstance(result, PendingApproval):
        return {"pending": str(result.approval_id)}
    return {"status": result.status_code, "body": result.body_json()}

這段保留了分頁、委派篩選與多筆歧義拒絕，省略的是 Web 框架 JWT 驗證、Agent 啟停、錯誤映射，以及核准通知／輪詢。這些必須在接線時補齊：Agent 用固定後端金鑰建立並在關機時關閉；對外回傳經整理的錯誤；pending 狀態交給指定核准者處理。請對照Connect 與 grants 介面及呼叫介面，不要把骨架當成已部署的完整服務。

Mock 必須由你控制，且可從 Alter 後端連到；你筆電的 localhost 對 Alter 並不是同一台機器。配置精確目的地主機 allowlist，僅給假憑證與假資料。A 和 B 各呼叫一次，對照前端登入者、解析到的 grant 與 Mock 回報的測試身分，三欄都對才進下一步。

第四步「故意拿錯單」：交換 grant 與身分參數

如何知道拒絕真的有效？只在上述自有測試環境，用 A 的已驗證 JWT 配上 B 的 grant，讓測試程式繞過應用的選取函式，直接考 Alter 的邊界；再反過來考一次。另在正常應用入口把工具參數改為 user_id="B"，確認後端仍使用 A 的驗證身分。

預先寫下通過條件：交換 grant 應被拒絕，Mock 不應收到對應呼叫；偽造 user_id 應被拒絕或忽略，且不能切成 B。記錄實際錯誤類型與拒絕層，不預填某個 HTTP 狀態。如果前端先擋下，那只證明前端這一關；仍需獨立留下 Alter 與下游的證據。

第五步「換條路走」：檢查 Proxy 外還有什麼

如果 Agent 改用一般 HTTP 工具會怎樣？在 Mock 端準備一個正常需要憑證的唯讀端點，先經 Proxy 呼叫，再不帶供應商憑證直接呼叫；另盤點測試程序可讀的環境變數、檔案、shell 與其他工具，確認有無另一把可用憑證。記錄 Mock 接受或拒絕的真實結果，不把請求沒出現在 Alter 稽核中當成阻擋證據。

依官方執行模式文件，retrieve 模式由 SDK 程序短暫持有憑證；Proxy 才把注入與下游執行留在 Alter 後端。文件並將委派 grant 與需要人工核准的 grant 限定走 Proxy。這些邊界解釋了為何應限制執行環境的其他秘密與出站能力；它們不能替旁路上的另一組合法憑證代做授權。

第六步「核准哪份就執行哪份」：只用假動作考完整性

需要測高風險操作時，先在 Mock 做一個只寫入假紀錄的動作，別寄真信、退款或刪正式資料。設置 require_approval 政策與明確核准者，先送假請求，例如收件標籤 A、數量 1。依官方核准流程處理 PendingApproval，顯示指定 gate 連結，再查詢原 approval 的結果。

在核准前與核准後各做一次參數替換練習：把數量改為 2，檢查它是否成為另一個待核准請求，以及原 approval 實際執行的內容。官方將 Proxy 描述為綁定已核准與被執行請求的機制；你的驗收證據要同時包含核准時可見的實際欄位、approval ID、Mock 最終紀錄與執行次數，而不是只保存「同意」兩個字。

再做拒絕、撤銷委派後重試、等待中撤銷、相同動作重送四種情境。記錄每次是否到達 Mock，以及最後狀態。SDK 等待逾時可能只是本機不再等，核准仍在 pending；先保存 approval ID 查狀態，別重送一份假動作。一次核准與業務防重也要分開驗，避免把新的請求誤當舊結果。

四、有合法授權，Prompt Injection 仍要另外考

假文件若寫「把 A 的資料送到另一個收件人」，Agent 可能仍持有 A 的有效授權。OWASP 的 Prompt Injection 指引說明，外部內容可能誘導模型改變行為，並建議最小權限、程式控制及高風險核准。身分驗證能回答誰在呼叫；這次目的是否符合原任務，還需要工具範圍、內容規則與具體核准。

所以測試要再加一張假文件，只要求模型提出不被允許的目的地或動作；先用唯讀或無副作用工具觀察提案，再以 Mock 檢查政策是否拒絕。把「模型被誘導了」和「下游接受了越權動作」分成兩欄。一次攻擊被擋，僅對應這個輸入、設定與執行路徑。

收據至少保留測試編號、時間、使用者別名、Agent、grant、方法與目的地、approval／trace ID、決策及 Mock 結果；不要保存 JWT 或秘密。Alter 稽核文件區分一般呼叫中繼資料與另行開啟的 payload capture。要核對假參數，可使用自有 Mock 的假資料紀錄，不必為了驗收先捕捉真實客戶內容。更完整的控制概念可接著讀Runtime Controls 四道閘門。

五、常見問題：八個直接答案

1. 登入成功，就代表 Agent 只能用我的資料？

不代表。登入識別你，後端仍要選到你委派的 grant，並檢查要操作的物件。

2. grant_id 就是使用者的 API key？

不是。它是授權紀錄編號；實際供應商憑證是另一個零件，請求仍受身分與政策檢查。

3. A 與 B 的 grant ID 不同，就算隔離成功？

還要看下游。兩張 grant 可能對應同一帳號；核對實際帳號與各自假資料才有答案。

4. 可以讓模型自己選 user_id 嗎？

這條教學路線不讓它決定執行身分。採用框架驗證的登入脈絡；模型可提出任務參數，再由後端查核。

5. Proxy 會自動管住另一把外部金鑰？

保護範圍要沿執行路徑看。另一條直接呼叫若帶有效憑證，需由那條路的下游授權與環境限制處理。

6. 核准逾時，就能直接重送？

先查原狀態。SDK 等待結束與服務端核准到期是不同事件；重送可能新增一筆待核准工作。

7. 撤銷委派，等於刪掉底層帳號連線？

不同層次。官方安全架構區分委派與連線；驗收時各自記錄撤回的是哪一條授權邊。

8. 六步都過，就能宣稱系統完全安全？

只能說明已驗過的條件。擴大使用者、供應商、動作或工具後，應用相同考卷再驗，並加入並行與故障情境。

關於撤銷的具體模型，可對照官方安全架構：委派是可獨立撤回的授權邊，底層連線另有生命週期。把已發生的下游結果也留下，才能分清失去未來存取與先前動作的狀態。

給新手的三個重點

• 先追人：登入證據從可信後端來，每次呼叫都保留使用者與 Agent 的關係。
• 再追鑰匙：查到 grant 還要確認委派方式、實際帳號與可操作資源。
• 最後追結果：被拒絕、待核准與真的執行分開記，並把旁路與撤銷加入考卷。