# App Store Connect API 金鑰建立與使用

> .p8 私鑰只能下載一次。本文說明如何建立 App Store Connect API 金鑰、選角色，並搭配 Expo 或 fastlane 使用。

原始頁面：[App Store Connect API 金鑰建立與使用](https://devoria.fr/zh-hant/blog/app-store-connect-api-key-p8-create-use)
作者：[Mehdi Azizi](https://devoria.fr/zh-hant/mehdi-azizi)
發布日期：2026-11-04
內容最後修訂：2026-11-04


App Store Connect API 金鑰讓 EAS、fastlane、RevenueCat 或你自己寫的腳本這類工具，不需要你的密碼和雙重認證，就能操作你的帳號。**Apple 保留金鑰的公開部分，私密部分是一個 `.p8` 檔，你只能下載一次。** 有了這個檔案、Issuer ID 和 Key ID，你就能簽發 token，大多數請求的 token 效期最長 20 分鐘。

我用 Expo 發布自己的 iOS app，包括 TradaZen 和 Nolera。我有一把 App Manager 角色的團隊金鑰，給 RevenueCat、我的 Expo build，還有一個用來編輯 App Store 頁面的命令列工具使用。這篇指南依據 2026 年 11 月 3 日重新查閱的 Apple、Expo 和 fastlane 官方頁面。別把它和放進 app 程式碼裡的第三方服務金鑰搞混：那些請看 [Expo app 裡的秘密 API 金鑰](https://devoria.fr/zh-hant/blog/expo-api-key-security-supabase)。

## App Store Connect API 金鑰的用途

根據 [Apple 的文件](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api)，App Store Connect API 的每個請求都需要一個 JWT token。你用私鑰產生並簽署它。這把金鑰只能用於這個 API，不能拿去用 Apple 的其他服務。

它的好處一句話就能說完：**不需要任何人手動確認登入。** 用 Apple ID 登入會卡在雙重認證，自動化就做不下去。[EAS Submit iOS](https://devoria.fr/zh-hant/blog/eas-submit-ios-expo-app-store) 這篇說明了它對上傳 Expo app 帶來的改變。

## 第一步：申請 API 存取權

第一把金鑰沒辦法直接建立。[App Store Connect 說明](https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api)寫得很清楚：**Account Holder 必須先申請 API 存取權。** 打開 Users and Access，點 Integrations，再點 Request Access。Apple 會逐案審核。

Account Holder 就是註冊帳號的那個人。如果你是新手，那就是你：註冊流程請看 [Apple 開發者帳號](https://devoria.fr/zh-hant/blog/apple-developer-account-price-free-or-99)。

## 團隊金鑰還是個人金鑰

Apple 提供兩種金鑰。以下差異整理自 [官方文件](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api)和 [App Store Connect 說明](https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api)：

| 項目                   | 團隊金鑰                | 個人金鑰         |
| ---------------------- | ----------------------- | ---------------- |
| 誰可以產生             | Account Holder 或 Admin | 幾乎所有使用者   |
| 可存取的 app           | 全部，沒有例外          | 該使用者的 app   |
| 權限                   | 所選的角色              | 該使用者的權限   |
| 金鑰數量               | 多把                    | 每人一把有效金鑰 |
| 憑證與描述檔           | 可以，視角色而定        | 不行             |
| 銷售、財務、notaryTool | 視角色而定              | 不行             |
| token 欄位             | `iss` = Issuer ID       | `sub` = `user`   |

依 Apple 的說法，「幾乎所有使用者」指的是 Account Holder、Admin、App Manager、Customer Support、Developer 和 Marketing，除非 Admin 或 Account Holder 取消了他們產生個人金鑰的權限。

**用 Expo 或 fastlane 的話，選團隊金鑰。** 個人金鑰無法存取 provisioning 相關的端點，也就是建立憑證和描述檔的那些。[fastlane 的文件](https://docs.fastlane.tools/app-store-connect-api/)也證實：所有和 provisioning 有關的存取都需要團隊金鑰。

## 該給金鑰什麼角色

不管角色為何，團隊金鑰都能存取帳號裡所有 app。角色決定的是它能做什麼。**Apple 提醒，Admin 金鑰可以新增和刪除使用者**：請給涵蓋你用途的最小角色。下表權限來自 [Apple 的角色表](https://developer.apple.com/help/account/access/roles/)。

| 金鑰用途                     | 允許的角色                    |
| ---------------------------- | ----------------------------- |
| 上傳 build                   | Admin、App Manager、Developer |
| 管理 TestFlight build        | Admin、App Manager            |
| 建立憑證和描述檔             | Admin、App Manager            |
| 送出 app 審查                | Admin、App Manager            |
| 匯入商品和價格（RevenueCat） | 至少 App Manager              |
| 產生其他團隊金鑰             | Admin                         |

RevenueCat 那一列來自[它的文件](https://www.revenuecat.com/docs/service-credentials/itunesconnect-app-specific-shared-secret/app-store-connect-api-key-configuration)。Expo 的指南則[給金鑰 Admin 角色](https://github.com/expo/fyi/blob/main/creating-asc-api-key.md)。在我的 app 上，App Manager 就夠了：EAS 用它建立發布用描述檔，RevenueCat 也能匯入商品。

金鑰產生之後，[名稱和角色都無法再修改](https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api)。要改，只能撤銷後重新產生一把。

## 一步步建立團隊金鑰

你需要 Admin 或 Account Holder 帳號。根據 [Apple](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api)：

1. **打開 Users and Access**，再點 Integrations 分頁。
2. **在左欄選 App Store Connect API**，再點 Team Keys 分頁。
3. **點 Generate API Key**，或點 + 按鈕。
4. **幫金鑰取名。** 名稱只給你自己看，不是金鑰的一部分。用會使用它的工具來命名。
5. **在 Access 下選擇角色**，然後點 Generate。
6. **用 Download API Key 連結下載私鑰。**

> 檔案下載完，下載連結就會消失，Apple 也不會保留任何副本。關掉頁面前先把 `.p8` 存好。

接著記下兩個識別碼。根據 [Apple 關於 token 的頁面](https://developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests)，**Issuer ID 顯示在 Integrations 頁面上方**，旁邊有 Copy 按鈕。Key ID 出現在有效金鑰清單裡：滑鼠移過去會出現 Copy Key ID。同一個帳號的所有團隊金鑰 Issuer ID 都一樣，Key ID 則每把不同。

個人金鑰更簡單：打開你的使用者個人資料，往下捲到 Individual API Key，點 Generate API Key。一樣只能下載一次。

## 保管 .p8 檔

Apple 要求把金鑰當密碼對待：**不要分享、不要放進程式碼儲存庫、絕對不要寫進 app 的程式碼。** 我的做法：

- **放在專案以外的資料夾**，或放在 CI 工具的秘密管理功能裡。
- **把金鑰資料夾加進 `.gitignore`**，如果上傳期間檔案必須暫放在專案裡。
- **嚴格的檔案權限。** 有個 App Store Connect 命令列工具，只要我的 `.p8` 還能被其他帳號讀取，就拒絕使用。一個 `chmod 600` 就解決了。
- **一個工具一把金鑰。** Apple 允許[產生多把金鑰](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api)，角色隨你選。

最後這點我一開始沒做到。我的 App Manager 金鑰同時給 RevenueCat、我的 build 和頁面編輯工具使用。如果必須撤銷它，三個工具會一起掛掉。**重來一次的話，我會一個工具建一把金鑰**，這樣停掉一把不會影響其他的。

## 搭配 Expo 使用

有三種方式把金鑰交給 EAS：

- **交給 EAS 管理。** `eas credentials --platform ios` 可以建立金鑰並存放在 Expo 的伺服器上。這是最簡單的做法。
- **寫在 `eas.json` 裡。** `submit` profile 接受 `ascApiKeyPath`、`ascApiKeyIssuerId` 和 `ascApiKeyId`。根據 [eas.json 參考文件](https://docs.expo.dev/eas/json/)，這些欄位可以用環境變數，例如 `$ASC_API_KEY_PATH`。
- **用環境變數傳入。** [EAS CLI 的儲存庫](https://github.com/expo/eas-cli/blob/main/packages/eas-cli/README.md)記載了 `EXPO_ASC_API_KEY_PATH`、`EXPO_ASC_KEY_ID` 和 `EXPO_ASC_ISSUER_ID`。個人金鑰則省略 Issuer ID。

build 有個限制要知道：[Expo 指出](https://docs.expo.dev/build-reference/ios-capabilities/)官方 API 無法綁定 App Group、Merchant ID 或 CloudKit 容器。這時需要在本機用 Apple ID 登入。我在 Nolera 的 widget app group 上就遇過：金鑰啟用了這項功能，卻沒有綁定群組。我是到 Apple 開發者網站手動綁定的。**如果 capability 同步卡住，`EXPO_NO_CAPABILITY_SYNC=1` 可以關掉它**，再自己在 App ID 上啟用該功能。build 的簽署細節請看 [iOS 憑證與 provisioning profile](https://devoria.fr/zh-hant/blog/ios-developer-certificate-provisioning-profile-expo)。

## 搭配 fastlane 使用

[fastlane](https://docs.fastlane.tools/app-store-connect-api/) 從 JSON 檔讀取金鑰。`key_id`、`issuer_id` 和 `key`（`.p8` 的內容）是必填欄位。`duration` 和 `in_house` 可選填。以下是假的值：

```json
{
  "key_id": "XXXXXXXXXX",
  "issuer_id": "your-issuer-id",
  "key": "-----BEGIN PRIVATE KEY-----\nMIGT...\n-----END PRIVATE KEY-----",
  "duration": 1200,
  "in_house": false
}
```

接著把這個檔案交給某個 action，例如 `fastlane pilot distribute --api_key_path fastlane/cle.json`。在 Fastfile 裡，`app_store_connect_api_key` action 接受 `key_id`、`issuer_id` 和 `key_filepath`。session 時間最長 1,200 秒，也就是 20 分鐘。不是每個 action 都支援：例如 fastlane 註明 `produce` 和 `pem` 無法搭配 API 金鑰使用。

## 在自己的腳本裡使用

不用工具的話，就自己產生 token。[Apple 規定了做法](https://developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests)：

- **標頭**：`alg` 為 `ES256`，`kid` 為你的 Key ID，`typ` 為 `JWT`。
- **內容，團隊金鑰**：`iss` 是你的 Issuer ID；`iat` 是建立時間；`exp` 是過期時間；`aud` 為 `appstoreconnect-v1`。
- **內容，個人金鑰**：用 `sub` 為 `user` 取代 `iss`。
- **效期**：超過 20 分鐘，大多數請求的 token 都會被 Apple 拒絕。

用 Python 的話，需要 PyJWT 函式庫和它的加密相依套件，依[它的文件](https://pyjwt.readthedocs.io/en/stable/installation.html)用 `pip install pyjwt[crypto]` 安裝。在 Mac 終端機要加引號：`pip install "pyjwt[crypto]"`，不然 zsh 會不接受方括號。

```python
import time
import jwt

KEY_ID = "XXXXXXXXXX"
ISSUER_ID = "your-issuer-id"

with open("AuthKey_XXXXXXXXXX.p8") as f:
    private_key = f.read()

now = int(time.time())
token = jwt.encode(
    {"iss": ISSUER_ID, "iat": now, "exp": now + 20 * 60, "aud": "appstoreconnect-v1"},
    private_key,
    algorithm="ES256",
    headers={"kid": KEY_ID, "typ": "JWT"},
)
print(token)
```

然後照 Apple 的範例，把它放進 `Authorization` 標頭送出：

```bash
curl -H "Authorization: Bearer $TOKEN" "https://api.appstoreconnect.apple.com/v1/apps"
```

我在 2026 年 11 月 3 日用一把在自己電腦上產生的拋棄式金鑰跑過這個腳本：token 的標頭和內容都符合 Apple 的頁面，ES256 簽章也驗證通過。我沒有拿這把測試金鑰去打 Apple 的 API，因為 Apple 那邊沒有這把金鑰。**token 還有效時就重複使用**：Apple 建議這樣做以取得較好的效能。

## 撤銷金鑰

金鑰一旦遺失、外洩，或某個工具不再使用，就撤銷它。根據 [App Store Connect 說明](https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api)，用 Account Holder 或 Admin 帳號：

1. 打開 Users and Access，再點 Integrations。
2. 選 Team Keys 或 Individual Keys，然後點 Edit。
3. 勾選要撤銷的金鑰，再點 Revoke Key。
4. 點 Revoke 確認。

**撤銷的金鑰永遠無法再啟用。** [Apple 會把它顯示](https://developer.apple.com/documentation/appstoreconnectapi/revoking-api-keys)在 Revoked 底下 30 天。所有用過它的工具都會認證失敗。在 Expo 上，錯誤訊息是「[App Store Connect rejected the API authentication credentials](https://github.com/expo/eas-cli/blob/main/packages/build-tools/src/steps/utils/ios/AscApiClient.ts)」。這個訊息和其他上傳失敗的原因，請看 [EAS 上傳錯誤與修正方法](https://devoria.fr/zh-hant/blog/eas-submit-ios-common-errors-fixes)。如果金鑰沒有外洩，先準備好新金鑰再停用舊的。如果已經外洩，Apple 要求立刻撤銷。

撤銷你自己的個人金鑰：個人資料、Individual API Key，然後 Revoke。

## 我的 .p8 金鑰檢查清單

- Account Holder 已申請 API 存取權。
- 如果要用於 build 或描述檔，就用團隊金鑰。
- 角色是涵蓋用途的最小角色，名稱標明是哪個工具在用。
- `.p8` 存放在儲存庫以外，權限嚴格，並有加密備份。
- Issuer ID 和 Key ID 另外記下，不和檔案放在一起。
- 每個工具各有一把金鑰，方便只撤銷其中一把。

## 自動化發布，又不讓金鑰外洩

金鑰只是整個流程中的一環。[iOS & Android Kit](https://devoria.fr/zh-hant/kits/ios) 從我 app 的起始程式碼出發（包含訂閱），用四個步驟帶你一路到 App Store，進度由你決定。如果你要用這把金鑰串接 RevenueCat，完整設定請看 [RevenueCat 與 iOS app 內訂閱](https://devoria.fr/zh-hant/blog/revenuecat-ios-in-app-subscription-setup)。

如果你正在準備第一次上架，[來做免費診斷](https://devoria.fr/zh-hant/diagnostic)：它會告訴你真正卡住你的是什麼，還會寄給你我的防 Apple 退件檢查清單。[在 App Store 上架 app](https://devoria.fr/zh-hant/expertise/publish-app-on-app-store) 這頁則逐一說明每個步驟，從 App Store 頁面到審核通過。

## 常見問題

### 如何建立 App Store Connect API 金鑰？

Account Holder 先申請 API 存取權。接著由 Admin 打開 Users and Access，Integrations 分頁，App Store Connect API，Team Keys。點 Generate API Key，取名並選角色，產生金鑰，再下載 `.p8` 檔。

### 遺失的 .p8 金鑰可以重新下載嗎？

不行。檔案只能下載一次，Apple 不會保留任何副本。撤銷遺失的金鑰，再產生一把新的，並更新每個用到它的工具。

### Issuer ID 和 Key ID 在哪裡找？

在 App Store Connect 的 Users and Access 選單，Integrations 分頁。Issuer ID 顯示在頁面上方，Key ID 在有效金鑰清單裡。個人金鑰不使用 Issuer ID。

### Expo 用的金鑰該給什麼角色？

Expo 的指南給的是 Admin 角色。根據 Apple 的角色表，App Manager 就足以上傳 build 以及建立憑證和描述檔。我用在 Expo build 的金鑰就是這個角色。

### API 金鑰的角色可以更改嗎？

不行。金鑰建立後，Apple 不允許修改名稱或角色。撤銷它，再用正確的角色產生一把新的。

### App Store Connect API 金鑰會過期嗎？

Apple 的頁面沒有提到金鑰會過期，只提到撤銷。會過期的是用它簽發的 token，大多數請求最長 20 分鐘。


## 你的專案

[Review Kit](https://devoria.fr/zh-hant/kits/app-review)：我的 App Store 審查檢查清單、我被 Apple 退件後的修正、Google Play 檢查清單，以及三個 Claude Code skill。$1,749。

[iOS & Android Kit](https://devoria.fr/zh-hant/kits/ios)：用 Claude Code 打造你的 iPhone 和 Android App：我自己 App 的起始程式碼、上架商店的完整流程，以及所有套件。$3,599。

[診斷：你離自己的 iPhone App 還差什麼](https://devoria.fr/zh-hant/diagnostic)：7 個問題，60 秒：找出真正卡住你發布 iPhone App 的原因，拿到你的 4 步驟路線，以及最適合你的套件。