developers · Oct 1, 2019

英雄出任務：用 Quire API 打造專屬應用程式

✦
AI 翻譯
· 查看英文版

Quire API

最後更新：2026 年 5 月 28 日

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

開發一個需要讀取或修改使用者 Quire 資料的應用程式，首先要解決的問題是：如何在不接觸使用者密碼的情況下完成驗證？Quire API 透過 OAuth 2.0 給出了答案。本文將帶你完整走過 OAuth 應用程式設定、四步驟授權流程、存取 Token 與更新 Token 的機制，以及開發者首次建置時最常犯的錯誤。

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

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

在開始接入 OAuth API 之前，先確認 API 是否真的是你需要的工具。Quire 在 2026 年支援四種整合介面，各自解決不同的問題。

如果你需要... 使用 原因
在自己的應用程式中代表使用者讀取或修改 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
  • Callback URL： 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 帳號與攻擊者的應用程式 Session 綁定。請為每次請求產生 state，存入 Session，並拒絕任何回傳 state 不符的 Callback。

3. 把存取 Token 當成永久有效。 存取 Token 在一小時後到期。應用程式若只儲存 Token 而從不更新，第一天運作正常，第二天就會悄悄失效。請在上線前就把更新 Token 的迴圈建置好，而不是等使用者抱怨才補救。

4. 輪詢 API 偵測變更。 輪詢會消耗速率限制、增加延遲、耗費電量。若需要回應 Quire 中的變更，請改用 Webhooks。Webhooks 會即時將事件推送給你，原本需要發出的 API 呼叫根本就不必發生。

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

如果你是第一次使用這個 API，最快的學習方式是 Fork 現有的整合範例，例如 n8n 連接器，研究它如何處理驗證、Token 更新與錯誤狀態。

什麼情況下 Quire API 不是最佳選擇？

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

  • 你只需要回應事件，而不需要查詢狀態。 Webhooks 更簡單、採推播式，且唯讀的事件訂閱不需要使用者授權。如果你的應用程式的任務是「有事發生時通知我」，用 Webhooks 而非 API。
  • 你在開發 Claude 或 LLM 代理整合。 Quire MCP 伺服器才是正確選擇。它負責處理驗證、提供標準化 Schema，讓你完全不必撰寫 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 存取 Token 的有效期限是多久？

存取 Token 預設在一小時後到期。更新 Token 的有效期限較長，可用來取得新的存取 Token，無需再次提示使用者授權。從第一天起就把更新 Token 的迴圈建置到應用程式中。

Quire API 可以只用於讀取資料嗎？

可以。OAuth Scope 讓你只申請應用程式所需的授權。如果應用程式只需讀取任務，申請讀取範圍的 Scope 即可。Quire 使用者在授權頁面可以看到所申請的 Scope，若要求範圍過大，他們可能會拒絕授權，因此過度申請 Scope 反而會降低轉換率。

Quire API 與 Quire MCP 伺服器有什麼差異？

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

接下來該怎麼做？

以上就是 Quire API 完整的 OAuth 2.0 流程：OAuth 應用程式設定、四步驟授權、存取 Token 使用，以及更新 Token 的機制。開發者最常遇到的情況是——整合運作正常，兩天後卻壞掉——原因幾乎都是把更新 Token 的迴圈留到以後再說，而不是從一開始就建置好。

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

Jimmy Shiau
Software Engineer