developers · Oct 1, 2019

成為英雄：用 Quire API 打造你自己的應用程式

✦
AI 翻譯
· 查看英文版

Quire API

最後更新：2026 年 5 月 28 日

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

開發一個讀取或修改用戶 Quire 資料的應用程式，首先要決定一件事：如何在完全不接觸用戶密碼的情況下完成身份驗證？Quire API 以 OAuth 2.0 解答了這個問題。本文將逐步說明 OAuth 應用程式設定、四步驟授權流程、存取權杖與更新循環，以及開發者首次建置時常見的錯誤。

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 開發者應用程式控制台

  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

回調範例如下：

//...
} 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 防偽權杖，用於驗證請求。

從查詢字串參數中提取 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);
     });
}

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

應用程式需要使用提取到的授權碼及以下請求參數，向權杖端點發出 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"
}

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

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

應用程式現在已取得存取權杖，可代表用戶進行 API 呼叫。

呼叫 API

在請求標頭中以 Bearer 權杖的形式傳入存取權杖，發出 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 存取權杖？

存取權杖的設計目的是短期使用，這是 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. 將客戶端金鑰存放在客戶端程式碼中。 客戶端金鑰顧名思義就是機密。一旦它出現在行動應用程式的執行檔或瀏覽器套件中，任何人都可以提取它並冒充你的應用程式。金鑰應只存放在你所控制的伺服器上。若你的應用程式是純客戶端架構（單頁應用程式、行動端），請使用 OAuth 2.0 PKCE 流程，而非嵌入金鑰。

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

3. 將存取權杖視為永久有效。 存取權杖在一小時後到期。應用程式若只儲存權杖而從不更新，第一天運作正常，第二天便會悄然失效。請在上線前先建置好更新權杖循環，而非等到用戶投訴時才修補。

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

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

若你是首次針對此 API 進行開發，最快的學習方式是 fork 一個現有整合（例如 n8n 連接器），研究它如何處理身份驗證、更新與錯誤狀態。

哪些情況下 Quire API 並不適合？

以下三種模式，應改用其他整合介面。

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

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

常見問題

Quire API 需要付費 Quire 方案嗎？

不需要。Quire API 在所有方案（包括免費層）均可使用。所有方案均適用速率限制；請查閱 API 文件 了解目前每個應用程式的限制。

Quire API 支援哪些程式語言？

此 API 以 HTTP 為基礎，使用 JSON 格式進行請求與回應，因此任何具備 HTTP 客戶端與 JSON 解析器的語言均可使用。本文的範例以 JavaScript 撰寫，但相同的流程同樣適用於 Python、Go、Ruby、PHP 及其他任何語言。官方並未提供客戶端函式庫；API 介面規模小，在你所使用語言的 HTTP 客戶端上加一層薄封裝已是常見做法。

Quire 存取權杖的有效期限是多久？

存取權杖預設在一小時後到期。更新權杖的有效期限較長，可用來在無需重新提示用戶的情況下取得新的存取權杖。請從第一天起就將更新權杖循環納入應用程式。

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

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

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

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

接下來怎麼做？

Quire API 的完整 OAuth 2.0 流程已全部介紹完畢：OAuth 應用程式設定、四步驟授權、存取權杖使用，以及更新循環。開發者交付一個運作正常的整合，卻在兩天後失效，最常見的原因就是將更新循環留待日後處理，而非從第一天起便納入其中。

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

Jimmy Shiau
Software Engineer