developers · Oct 1, 2019

英雄出少年：用 Quire API 打造你自己的應用程式

✦
AI 翻譯
· 查看英文版

Quire API

最後更新：2026 年 5 月 28 日

TL;DR：Quire OAuth 2.0 API 讓你的應用程式無需儲存使用者密碼，即可代表使用者操作其 Quire 帳號。你需要一個已註冊的 OAuth 應用程式（包含客戶端 ID、金鑰與重新導向網址）、四步驟授權流程（設定、重新導向、處理回應、以授權碼換取 token），以及 refresh token 循環機制——因為存取權杖在一小時後就會失效。

開發一個讀取或修改使用者 Quire 資料的應用程式，首先要做一個決定：如何在不取得使用者密碼的情況下完成驗證？Quire API 透過 OAuth 2.0 解決了這個問題。本文將帶你完整了解 OAuth 應用程式設定、四步驟授權流程、存取權杖與 refresh 循環，以及開發者在首次建構時常犯的錯誤。

Quire OpenAPI 1.0.0 版本於 2019 年 10 月發布，至今維持穩定。透過 OAuth，使用者授權你的應用程式存取其 Quire 內容（任務、專案、留言、指派、標籤、到期日期），而你完全不會碰到他們的登入憑證。使用者隨時可以撤銷授權，且無需更改密碼——這正是為什麼在 OAuth 普及之前，儲存密碼的整合方式是公認的資安反模式。

哪種 Quire 整合方式最適合你的需求？

在串接 OAuth API 之前，先確認 API 是否真的是最合適的工具。2026 年 Quire 提供四種整合介面，各自解決不同的問題。

需求 使用方式 原因
在自己的應用程式中代表使用者讀取或修改 Quire 資料 Quire OAuth API（本文） 使用者授權、完整 CRUD 存取、無需輪詢
即時回應 Quire 中的事件（任務建立、狀態變更、新增留言） Quire Webhooks 推送式架構、無輪詢負擔、設定輕便
將 Quire 串接至 Claude 或其他 AI 代理人 Quire MCP 伺服器 LLM 工具標準協議，內建預建伺服器
將 Quire 整合至自動化或 BI 工作流程 OAuth API 搭配 n8n 或 Power BI 成熟的整合管道，減少自訂程式碼

如果你要開發的是一般應用程式整合（行動 App、網頁儀表板、同步服務），OAuth API 就是你需要的工具。本文後續皆以此為前提繼續說明。

如何為 Quire API 設定 OAuth 應用程式？

要使用 Quire API，你需要先建立一個 OAuth 應用程式。

建立你的 Quire OAuth 應用程式

你需要登入 Quire 帳號才能建立應用程式。

  1. 前往 Quire 開發者應用程式主控台，點擊 建立新的應用程式 按鈕。 Quire 開發者應用程式主控台

  2. 選擇你的應用程式所屬的 Quire組織；該組織的成員將可以檢視或編輯隸屬於此組織的所有應用程式。 Quire 應用程式組織

  3. 為你的應用程式命名並填入重新導向網址，後續我們會說明重新導向網址的用途。目前可以先填入以下網址：

    http://localhost:3000/callback

  4. 點擊 建立新的應用程式 按鈕，新建立的 OAuth 應用程式將顯示在開發者主控台頁面，供你進一步設定。 Quire 應用程式列表

完成後，你應該擁有以下三項資訊：

  • 開發客戶端ID： :wJoMEodI4fSSR54pfNwIuIzLnaJ
  • 開發客戶端金鑰： eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex
  • 回呼網址： http://localhost:3000/callback

Quire 應用程式憑證

如何設定 Quire API 的開發環境？

步驟一：設定你的應用程式

將應用程式的設定資訊存放於你的應用程式中。

const clientId = ':wJoMEodI4fSSR54pfNwIuIzLnaJ';
const clientSecret = 'eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex';
const redirectURI = 'http://localhost:3000/callback';
  
const authorizationUrl = 'https://quire.io/oauth';
const tokenUrl = 'https://quire.io/oauth/token';
const apiUrl = 'https://quire.io/api';

步驟二：將使用者重新導向至 Quire 進行授權

產生一個授權網址，將使用者重新導向至 Quire 的 OAuth 端點 URI。系統會顯示一個網頁，讓已登入的 Quire 使用者授權你的應用程式存取其內容。

範例網址：

https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri

授權連結的範例如下：

var http = require('http');
var url = require('url');
var server = http.createServer(function (req, res) { 
    var uri = url.parse(req.url, true);
    if (uri.pathname == '/') {        
        //..    
    } else if (uri.pathname == "/install") {
        var authUrl = authorizationUrl 
            + '?client_id=' + clientId 
            + '&redirect_uri=' + encodeURIComponent(redirectURI);
        res.writeHead(200, { 'Content-Type': 'text/html' });
        res.write(
             '<html><body>' 
            + '<a href="' + authUrl + '">Connect Quire</a>' 
         + '</body></html>');
        res.end();

    } else if (uri.pathname == "/callback") {
        //...
    }
});
server.listen(3000);

state 參數是一個隨機字串，用於防止跨站請求偽造（CSRF）攻擊。你應該隨機產生一組字元字串，它將在步驟三中原封不動地回傳給你的應用程式。應用程式應驗證此值。雖然這是選填參數，但我們強烈建議加入。

範例網址：

https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri&state=lpcl9v94z

步驟三：處理 OAuth 2.0 伺服器回應

OAuth 2.0 伺服器會透過 redirect_uri 中指定的網址回應你的存取請求。

若使用者核准存取請求，回應中將包含授權碼。若使用者不核准，回應中則會包含錯誤訊息。授權碼或錯誤訊息會以查詢字串的形式回傳至網頁伺服器，如下所示：

錯誤回應：

http://localhost:3000/callback?error=access_denied

授權碼回應：

http://localhost:3000/callback?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Callback 範例如下：

//...
} else if (uri.pathname == "/callback") {
   var result = uri.query;
   var message = 'Auth fail';
   if (result["error_description"] != null) {
       message = result["error_description"];
       if (result["error"] == 'access_denied') {
           //display reject message
       }
       messageView(res, message);
   } else if (result["code"] != null) {
       return exchangeAccessToken(result["code"])
       .then(function(data) {
            var token = data['access_token'];
            message = token != null ? 'Success': 'Fail';
            messageView(res, message);
        });
   }
}

當使用者被重新導向回應用程式的 redirect_uri 時，查詢字串參數中也會包含 code 和 state 參數。其中 state 是你的 CSRF 防偽 token，用於驗證請求合法性。

從查詢字串參數中取出 code 和 state。此時可以驗證 state 的值。

驗證範例如下：

} else if (result["code"] != null) {
    if (result["state"] != stateFromSession(res))
        return messageView(res, 'invalid state');
            
    return exchangeAccessToken(result["code"])
    .then(function(data) {
         var token = data['access_token'];
         message = token != null ? 'Success': 'Fail';
         messageView(res, message);
     });
}

步驟四：以授權碼換取存取權杖

你的應用程式需要向 token 端點發送 POST 請求，帶上取得的授權碼及以下請求參數。

參數 值
grant_type authorization_code
code {your-authorization-code}
client_id {your-client-ID}
client_secret {your-client-secret}
redirect_uri 若在步驟二中指定了 redirect_uri，此處為必填，且值必須與步驟二中使用的完全相同。

請求存取權杖的範例如下：

var request = require('request');
function exchangeAccessToken(code) {
    return new Promise(function(resolve, reject){
        request.post({
            url: tokenUrl,
            form: {
              grant_type: 'authorization_code',
              code: code,
              client_id: clientId,
              client_secret: clientSecret,
              redirect_uri: redirectURI
            }
          },
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

回應中收到的存取權杖為 JSON 格式。

回應範例：

{ 
  "access_token":"ACCESS_TOKEN", 
  "token_type": "bearer", 
  "expires_in":2592000, 
  "refresh_token":"REFRESH_TOKEN"
}

請妥善且永久保存此 token，因為每次存取 Quire API 都需要用到它。

如何使用 Quire 存取權杖進行 API 呼叫？

你的應用程式現在已取得存取權杖，可以代表使用者進行 API 呼叫。

呼叫 API

進行 API 呼叫時，將存取權杖以 bearer token 的形式放在請求標頭中傳送。

API 呼叫範例如下：

function getCurrentUser(token) {
    return new Promise(function(resolve, reject){
        request.get({
            url: apiUrl + '/user/id/me', 
            headers: {
              "Authorization": "Bearer " + token
            }
          }, 
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

回應範例：

{
  "email": "john@gmail.cc",
  "website": "https://coolwebsites.com",
  "id": "My_ID",
  "description": "This is *cool*!",
  "url": "https://quire.io/u/My_ID",
  "nameText": "My Name",
  "nameHtml": "My Name",
  "descriptionText": "This is cool!",
  "descriptionHtml": "This is <i>cool</i>!",
  "image": "https://quire.s3.amazonaws.com/oid/image.jpg",
  "iconColor": "37",
  "name": "My Name",
  "oid": "Dyh2YkFcu9uLgLFIeN1kB4Ld"
}

如何更新已過期的 Quire API 存取權杖？

存取權杖在設計上僅供短期使用，這是 OAuth 2.0 重要的安全機制之一。使用授權碼授權流程時，存取權杖預設的有效期為一小時。

當存取權杖過期時，系統會回傳 HTTP 401 錯誤：

{ 
  code: 401, 
  message: 'Invalid or expired token.' 
}

Your application will need to refresh the access token. 
function refreshToken(refreshToken) {
    return new Promise(function(resolve, reject){
        request.post({
            url: tokenUrl, 
            form: {
              grant_type: 'refresh_token',
              refresh_token: refreshToken,
              client_id: clientId,
              client_secret: clientSecret
            }
          }, 
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

此外，你也可以將使用者重新導向至身份驗證流程。

開發者使用 Quire API 最常犯哪些錯誤？

觀察許多團隊串接 Quire API 的過程後，我們發現同樣五個問題反覆出現。這些問題都不難察覺，也完全可以避免。

1. 將客戶端金鑰寫入前端程式碼。 客戶端金鑰顧名思義是機密資訊。一旦被嵌入行動 App 二進位檔或瀏覽器打包檔，任何人都可以提取並冒充你的應用程式。金鑰應僅存放於你自己控制的伺服器上。若你的應用程式純粹是前端（單頁應用程式、行動 App），請改用 OAuth 2.0 PKCE 流程，而非將金鑰嵌入程式碼。

2. 忽略 state 參數的驗證。 state 參數的存在是為了防止 CSRF 攻擊。若你在 callback 時略過驗證，便留下了漏洞，讓惡意網站得以將 Quire 帳號悄悄與攻擊者的應用程式 session 綁定。請為每次請求隨機產生 state，將其儲存於 session 中，並拒絕任何回傳 state 不符的 callback。

3. 將存取權杖視為永久有效。 存取權杖在一小時後失效。應用程式若儲存了 token 卻從不更新，第一天運作正常，第二天就會悄悄出錯。請在上線前就建立好 refresh token 循環，而非等到使用者回報問題後才修補。

4. 輪詢 API 偵測變更。 輪詢會消耗頻率配額、增加延遲、耗費電量。若需要即時回應 Quire 中的變更，請改用 webhooks。Webhooks 會在事件發生時立即推送給你，那些用來偵測變更的 API 呼叫就完全不必發出。

5. 略過重新導向網址白名單設定。 每個 OAuth 應用程式註冊時都可以設定允許的重新導向網址清單。若你使用萬用字元或未精確設定，攻擊者便可將自己的 callback 偽裝成你的重新導向目標，從而攔截授權碼。請只填入應用程式實際使用的確切網址。

如果你是第一次串接此 API，最快速的學習方式是參考現有的整合專案，例如 n8n connector，研究它如何處理驗證、refresh 與錯誤狀態。

什麼時候 Quire API 不是最佳選擇？

以下三種情境建議改用其他整合介面。

  • 你只需要回應事件，不需要查詢狀態。 Webhooks 更簡單、採推送架構，且唯讀事件訂閱不需要使用者授權。若你的應用程式只是「發生某事時通知我」，請用 webhooks，而非 API。
  • 你正在開發 Claude 或 LLM 代理人整合。 Quire MCP 伺服器是這種情境的正確選擇。它負責處理驗證、提供標準結構，讓你無需自行撰寫 OAuth 程式碼。MCP 本就是為此而生；用 OAuth API 自行打造反而是用更多力氣換到相同結果。
  • 你只需要一次性資料匯出。 若只是要拉取某個專案的資料進行分析或備份，使用 n8n 整合或手動匯出 CSV 可以省下一週的開發時間。

若以上情境都不適用，OAuth API 就是你的工具。

常見問題

使用 Quire API 需要付費方案嗎？

不需要。Quire API 在所有方案（包含免費版）均可使用。所有方案皆有頻率限制；請參閱 API 文件了解目前各應用程式的限制。

Quire API 支援哪些程式語言？

此 API 採用 HTTP 傳輸、JSON 格式請求與回應，因此任何具備 HTTP 客戶端與 JSON 解析器的語言皆可使用。本文範例使用 JavaScript，但相同流程同樣完全適用於 Python、Go、Ruby、PHP 及其他語言。官方未提供客戶端函式庫，因為 API 介面相當精簡，在你慣用語言的 HTTP 客戶端上加一層薄封裝即為常見做法。

Quire 存取權杖有效期多長？

存取權杖預設在一小時後失效。Refresh token 的有效期較長，可用來取得新的存取權杖，無需再次提示使用者重新授權。請從開發之初就將 refresh token 循環機制寫入應用程式。

Quire API 可以用於唯讀存取嗎？

可以。OAuth 範疇（scopes）讓你只申請應用程式所需的權限。若應用程式只需讀取任務，申請讀取範疇即可。Quire 使用者在授權頁面上可以看到所申請的範疇，若範疇過多會令人卻步，因此過度申請反而會降低轉換率。

Quire API 與 Quire MCP 伺服器有何不同？

API 是通用型 REST 介面，適用於任何需要代表使用者讀取或修改 Quire 資料的應用程式。MCP 伺服器則是專為 Claude 及其他 LLM 代理人設計：它處理驗證、提供標準工具結構，讓你無需自行撰寫 OAuth 程式碼。傳統應用程式整合請使用 API；LLM 代理人整合請使用 MCP。

接下來要做什麼？

以上就是 Quire API 完整的 OAuth 2.0 流程：OAuth 應用程式設定、四步驟授權、存取權杖使用，以及 refresh 循環。開發者上線後兩天整合就壞掉，最常見的原因就是把 refresh 循環當成事後再補的工作，而非從一開始就建立好。

前往 Quire 開發者應用程式主控台開始開發，或閱讀完整的 API 參考文件。若你不想自己撰寫 OAuth 程式碼，Quire MCP 伺服器會幫你處理驗證，是 LLM 代理人整合的最佳選擇。若需要事件驅動整合，webhooks 通常比大多數初次 API 整合最終採用的輪詢模式更為適合。

Jimmy Shiau
Software Engineer