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 循環機制——因為存取 token 會在一小時後失效。

開發一個讀取或修改用戶 Quire 資料的應用程式，首先要面對的問題是：如何在不接觸用戶密碼的情況下完成身份驗證？Quire API 的答案是 OAuth 2.0。本文將逐步介紹 OAuth 應用程式設定、四步驟授權流程、存取 token 與 refresh token 循環機制，以及開發者首次構建時最常犯的錯誤。

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 成熟的管道方案，減少自訂程式碼

若你正在構建典型的應用程式整合（行動應用程式、網頁儀表板、同步服務），OAuth API 正是你所需要的。本文其餘部分均基於此前提。

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

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

建立你的 Quire OAuth 應用程式

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

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

  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

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

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

申請存取 token 的示例如下：

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))
          });
    });
}

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

回應示例：

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

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

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

你的應用程式現在已獲得存取 token，可代表用戶進行 API 呼叫。

呼叫 API

在請求標頭中以 bearer token 的形式傳入存取 token，即可進行 API 呼叫。

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 存取 token？

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

存取 token 過期後，將返回 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. 將客户端密鑰存放於客户端程式碼中。 客户端密鑰顧名思義就是機密。若它出現在行動應用程式的二進位檔或瀏覽器套件中，任何人都可以提取並冒充你的應用程式。密鑰應只存放在你所控制的伺服器上。若你的應用程式純粹是客户端（單頁應用程式、行動應用程式），請使用 OAuth 2.0 PKCE 流程，而非嵌入密鑰。

2. 忘記驗證 state 參數。 state 參數的存在是為了防止 CSRF 攻擊。若你在 callback 中跳過驗證，就留下了一個漏洞，惡意網站可利用它悄悄將 Quire 帳戶與攻擊者的應用程式會話關聯起來。請為每個請求生成 state，將其存入會話，並拒絕任何返回 state 與之不符的 callback。

3. 將存取 token 視為永久有效。 存取 token 在一小時後失效。那些儲存 token 卻從不刷新的應用程式，第一天運行正常，第二天就會悄然崩潰。請在上線前就建立 refresh token 循環機制，而非等到用戶投訴才修補。

4. 輪詢 API 以偵測變更。 輪詢會消耗速率限制配額、增加延遲並耗費電量。若需要回應 Quire 中的變更，請改用 Webhooks。Webhooks 會即時將事件推送給你，讓你完全不需要進行原本用於偵測事件的 API 呼叫。

5. 跳過重新導向網址白名單設定。 每個 OAuth 應用程式註冊時都接受一組重新導向網址列表。若你使用萬用字元或未精確設定，攻擊者可將其 callback 註冊為你的重新導向目標，從而攔截授權碼。請只添加你的應用程式實際使用的確切網址。

若你是首次對接此 API，最快的學習方式是參考現有整合方案（例如 n8n 連接器），研究它如何處理身份驗證、token 刷新和錯誤狀態。

何時 Quire API 並非最佳選擇？

以下三種情況下，你應考慮使用其他整合介面。

  • 你只需要回應事件，而非查詢狀態。 Webhooks 更為簡單，採用推送式機制，唯讀事件訂閲也無需用戶授權。若你的應用程式目標是「有事發生時通知我」，請使用 Webhooks，而非 API。
  • 你正在構建 Claude 或 LLM 代理整合。 Quire MCP 伺服器才是此場景的正確選擇。它負責處理身份驗證、提供標準架構，讓你無需自行撰寫 OAuth 程式碼。MCP 專為此而設；用 OAuth API 自行實現只是以更多工作換取相同結果。
  • 你只需要進行一次性資料匯出。 若你只需提取某個專案的資料一次以供分析或備份，n8n 整合或手動 CSV 匯出可為你省去一週的開發時間。

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

常見問題

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

不需要。Quire API 適用於所有方案，包括 Free 版。所有方案均受速率限制約束；請查閱 API 文件 了解目前每個應用程式的具體限制。

Quire API 支援哪些程式語言？

此 API 以 HTTP 為基礎，使用 JSON 格式進行請求與回應，因此任何具備 HTTP 客户端和 JSON 解析器的語言皆可使用。本文的範例使用 JavaScript，但相同的流程同樣適用於 Python、Go、Ruby、PHP 及其他語言。官方不提供客户端函式庫；在你所用語言的 HTTP 客户端基礎上進行薄封裝是最常見的做法，因為 API 介面已足夠精簡。

Quire 的存取 token 有效期多長？

存取 token 預設在一小時後失效。Refresh token 的有效期較長，可用於在不再次提示用戶的情況下取得新的存取 token。從第一天起就將 refresh token 循環機制納入應用程式。

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

可以。OAuth 授權範圍讓你只需申請應用程式所需的授權。若應用程式只需讀取任務，申請讀取範圍即可。Quire 用戶會在授權頁面上看到所申請的授權範圍，若覺得申請範圍過大可拒絕授權，因此過度申請授權會影響轉換率。

Quire API 與 Quire MCP 伺服器有何分別？

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

接下來怎麼做？

以上就是 Quire API 完整的 OAuth 2.0 流程：OAuth 應用程式設定、四步驟授權、存取 token 使用，以及 refresh token 循環機制。開發者構建出可運行的整合卻在兩天後崩潰，最常見的原因正是將 refresh token 循環視為日後再解決的問題，而非從第一天就內建於應用程式之中。

立即前往 Quire 開發者應用程式控制台開始開發，或閱讀完整的 API 參考文件。若你完全不想撰寫 OAuth 程式碼，Quire MCP 伺服器可為你處理身份驗證，是 LLM 代理整合的正確選擇。對於事件驅動的整合，Webhooks 通常比大多數首次接入 API 的整合方案最終採用的輪詢模式更為合適。

Jimmy Shiau
Software Engineer