登入開始免費試用
easyCoexistence 官方 API

Partner API 驗證:Bearer ec_live_ 密鑰、輪換與 401 錯誤

每個 Partner API 請求都會在 Authorization 標頭中攜帶帳戶的密鑰,格式為 Bearer ec_live_…,並由您的伺服器發送。每個 easyCoexistence 帳戶只有一把密鑰,可在控制台中的「個人檔案」→「開發者」建立,或要求 AI 助理執行 create_api_key 建立,且只會顯示一次。輪換會發出新密鑰,並即時停用舊密鑰;缺少或錯誤的密鑰會收到 401 unauthorized。

ec_live_

每把 Partner API 密鑰開頭的前綴,每個請求均以 Authorization: Bearer 形式發送。

1 key

帳戶同時持有的密鑰數目;以該密鑰建立的每個連接均屬於此帳戶。

401

缺少或無效密鑰的狀態碼,錯誤代碼為 unauthorized,訊息會註明預期的標頭。

Once

顯示完整密鑰的時機為建立或輪換時;之後只會顯示其前幾個字元。

請求如何驗證?

每個發往 https://easycoexistence.com/api/v1 的請求,都須在 Authorization 標頭中以 Bearer 存取權杖的形式攜帶此密鑰。除此之外,不需要簽署或限定範圍:密鑰用以識別帳戶,請求所建立或讀取的所有內容均屬於該帳戶。請求內容為 JSON,所有錯誤均以包含 code 與 message 的物件返回。

List the account's numbers
curl https://easycoexistence.com/api/v1/connections \
  -H "Authorization: Bearer $EC_API_KEY"

在哪裡建立密鑰?

可在控制台建立,亦可由 AI 助理建立,結果相同。在控制台中,開啟「個人檔案」,再選擇「開發者」,然後按「建立 API 密鑰」。在已連接 easyCoexistence MCP 伺服器的 Claude、ChatGPT 或其他 AI 助理中,要求它設定 Partner API:get_partner_setup 會顯示缺少的項目,create_api_key 則會返回密鑰。無論以哪種方式,完整密鑰都只會顯示一次,請立即將其存放於後端的機密設定中。

為何密鑰只顯示一次?

因為系統只儲存其雜湊值。easyCoexistence 保留雜湊值以驗證每個請求,並保留密鑰的前幾個字元,即 ec_live_ 加六個字元,讓控制台能顯示目前有效的密鑰及其建立時間。遺失的密鑰無法再次顯示;輪換則會將其取代。

如何輪換或撤銷密鑰?

一步完成,舊密鑰會於該瞬間停止運作,且沒有寬限期,因為密鑰外洩通常是需要輪換的主因。新密鑰與首次建立時一樣只顯示一次:

  • 控制台:「個人檔案」、「開發者」、「輪換密鑰」。
  • MCP:呼叫 create_api_key 並將 replace_existing 設為 true。若不設定,工具會在密鑰已存在時拒絕執行,以免正在運作的整合意外中斷。
  • 若要改為停止所有存取,請撤銷:在控制台中按「撤銷」,或呼叫 revoke_api_key 並將 confirm 設為 true。之後請求會失敗,直至建立新密鑰為止。

缺少或錯誤的密鑰會返回什麼?

若請求沒有 Authorization 標頭、密鑰不是以 ec_live_ 開頭,或密鑰已被輪換或撤銷,會返回 401,錯誤代碼為 unauthorized。訊息會註明預期的標頭。若失敗請求持續來自同一個 IP 位址,API 會改為返回 429 rate_limited,並附上需等待的秒數,然後才可重試。

401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Send `Authorization: Bearer ec_live_...`."
  }
}

有效密鑰還可能被拒絕嗎?

有效密鑰只能證明帳戶身分,帳戶的狀態仍然適用。以下情況會返回相同格式的錯誤:

  • 402 billing_required:帳戶尚未新增信用卡,因此無法開始連接會話。
  • 404 not_found:此 id 不屬於本帳戶的任何連接、頻道或會話,包括其他帳戶的項目。
  • 409 removed:連接已被移除,因此其 webhook 無法再作更改。
  • 402 suspended:訂閱失效後連接已被暫停;請先重新連接。
  • 429 cap_reached 或 rate_limited:開啟的連接會話過多,或本小時內建立的會話過多。

常見錯誤

  • 將密鑰放在前端程式碼中。任何人打開頁面都可以讀取,並藉此建立以您名義計費的連接,或透過 ?credentials=1 取得您客戶的存取權杖。
  • 在後端尚未能接受新密鑰前便進行輪換。舊密鑰會立即失效,因此在新密鑰部署之前,每個請求都會返回 401。
  • 在共享的對話中建立密鑰。create_api_key 會在對話中返回密鑰,該內容會保留在紀錄中,因此若該對話曾被分享,請將密鑰輪換。
  • 將密鑰以引號包住後存放。Bearer 之後的所有內容都會被視為密鑰,因此加了引號的值永遠不會匹配,每個請求都會返回 401。
使用 EasyCoexistence 完成這項設定

easyCoexistence 為每個帳戶提供一把 Partner API 密鑰,讓您的後端可以連接客戶的 WhatsApp 號碼,以及其 Instagram、Facebook、TikTok、YouTube 與 LinkedIn 帳戶,以及更多頻道,然後讀取每個連接的憑證並接收其事件。每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 天免費。

常見問題

一個帳戶可以有多於一把 API 密鑰嗎?

不可以。一個帳戶同時只能有一把密鑰,建立新密鑰會取代舊的。如需獨立密鑰,請使用不同的 easyCoexistence 帳戶,每個帳戶各有自己的連接及帳單。

Partner API 密鑰會過期嗎?

不會。密鑰會一直有效,直至被輪換或撤銷,或因違反 Meta 規則而被 easyCoexistence 終止為止。

客戶需要我的密鑰才能連接嗎?

不需要。他們只需開啟託管的連接連結,該連結附有自己的會話 id。密鑰只留在您的伺服器上,並僅由後端使用。

API 密鑰與事件簽署密鑰是同一個嗎?

不是。API 密鑰用於驗證您發往 API 的請求。簽署密鑰會在您設定狀態事件網址時顯示一次,讓您的端點能驗證 easyCoexistence 發送的事件。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期