developers · Oct 1, 2019
成為英雄：用 Quire API 打造專屬應用程式
最後更新：2026 年 7 月 20 日
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 真的是合適的工具。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 帳號，才能建立應用程式。
前往 Quire 開發者應用程式主控台，點選 建立新的應用程式 按鈕。
選擇應用程式所屬的 Quire組織，該組織的成員可以檢視／編輯屬於所選組織的所有應用程式。
為應用程式命名並填寫重新導向網址，我們稍後會說明重新導向網址的作用。目前你可以先填入以下網址：
http://localhost:3000/callback點選 建立新的應用程式 按鈕，新建立的 OAuth 應用程式會顯示在開發者主控台頁面，讓你進一步設定。
總結來說，你應該已取得這三項資訊：
- 開發客戶端ID： :wJoMEodI4fSSR54pfNwIuIzLnaJ
- 開發客戶端金鑰： eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex
- 回呼網址：
http://localhost:3000/callback
如何為 Quire API 設定開發環境？
步驟 1：設定你的應用程式
把應用程式的設定資訊放在你的應用程式中。
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';步驟 2：將使用者重新導向至 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）攻擊。請隨機產生一串字元，它會在步驟 3 原封不動地回傳給你的應用程式，你的應用程式應該驗證這個值。雖然這個參數是選填，我們強烈建議加上。
範例網址：
https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri&state=lpcl9v94z步驟 3：處理 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);
});
}步驟 4：以授權碼換取存取權杖
你的應用程式需要使用取得的授權碼與下列請求參數，對權杖端點發出 POST 呼叫。
| 參數 | 值 |
|---|---|
| grant_type | authorization_code |
| code | {your-authorization-code} |
| client_id | {your-client-ID} |
| client_secret | {your-client-secret} |
| redirect_uri | 若你在步驟 2 指定了 redirect_uri，此欄位為必填，且其值必須與步驟 2 使用的完全相同。 |
請求存取權杖的範例可能如下：
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
呼叫 API 時，把存取權杖當作 bearer 權杖放在請求標頭中。
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 的重要安全機制。使用授權碼授權流程（Authorization Code Grant Flow）時，存取權杖預設的有效期限為一小時。
存取權杖過期時，會回傳 HTTP 401 錯誤：
{
code: 401,
message: 'Invalid or expired 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，最快學會這些模式的方法，就是複製一個現有的整合（例如 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 範圍（scope）讓你只請求應用程式所需的授權。如果應用程式只讀取任務，就只請求讀取範圍。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 整合最後採用的輪詢方式更適合。而如果你只是想快速用腳本做些變更，完全不想建立 OAuth 應用程式，Quire 的 CLI 可以直接在終端機執行專案管理指令。
