developers · Oct 1, 2019

Будь героем: создай своё приложение с помощью Quire API

✦
Переведено ИИ
· Смотреть на английском

Quire API

Последнее обновление: 28 мая 2026 г.

Кратко: Quire OAuth 2.0 API позволяет приложению действовать от имени пользователя в его аккаунте Quire, не сохраняя пароль. Вам понадобится зарегистрированное OAuth-приложение (ID клиента, секрет, URL-адрес для перенаправления), четыре шага авторизации (настройка, перенаправление, обработка ответа, обмен кода на токен) и цикл обновления токенов — поскольку токены доступа истекают через один час.

Разработка приложения, которое читает или изменяет данные Quire пользователя, начинается с одного решения: как аутентифицировать пользователя, не видя его пароля? Quire API решает эту задачу с помощью OAuth 2.0. В этой статье разберём настройку OAuth-приложения, четыре шага авторизации, цикл работы с токенами доступа и типичные ошибки разработчиков при первой реализации.

Версия 1.0.0 OpenAPI Quire вышла в октябре 2019 года и с тех пор остаётся стабильной. С OAuth пользователи разрешают приложению доступ к своему контенту в Quire (задачи, проекты, комментарии, назначения, метки, даты выполнения), и вы никогда не касаетесь их учётных данных. Пользователь может отозвать доступ в любое время, не меняя пароль — именно поэтому интеграции с хранением паролей считались антипаттерном безопасности ещё до того, как OAuth сделал их ненужными.

Какой подход к интеграции Quire подходит для вашей задачи?

Прежде чем подключать OAuth API, убедитесь, что он действительно нужен. В 2026 году Quire поддерживает четыре способа интеграции, каждый из которых решает свою задачу.

Если вам нужно... Используйте Почему
Читать или изменять данные Quire от имени пользователя в своём приложении Quire OAuth API (эта статья) Авторизация пользователя, полный CRUD-доступ, опрос не нужен
Реагировать на события в Quire (создана задача, изменился статус, добавлен комментарий) Вебхуки Quire Push-механизм без накладных расходов на опрос, простая настройка
Подключить Quire к Claude или другому AI-агенту Сервер Quire MCP Стандартный протокол для LLM-инструментов, поставляется с готовым сервером
Интегрировать Quire в автоматизацию или BI-процесс OAuth API и n8n или Power BI Готовые пайплайны, минимум кастомного кода

Если вы создаёте стандартную интеграцию (мобильное приложение, веб-дашборд, сервис синхронизации), OAuth API — то, что нужно. Дальнейший текст предполагает именно этот сценарий.

Как настроить OAuth-приложение для Quire API?

Чтобы использовать Quire API, необходимо создать OAuth-приложение.

Создайте OAuth-приложение Quire

Для создания приложения нужно быть авторизованным в аккаунте Quire.

  1. Перейдите в консоль разработчика Quire и нажмите кнопку Создать новое приложение. Quire developer app console

  2. Выберите Организацию в Quire, к которой будет относиться приложение: участники организации смогут просматривать и редактировать все Приложения, принадлежащие выбранной организации. Quire app организация

  3. Задайте название приложения и URL-адрес для перенаправления — о его роли мы поговорим позже. Пока укажите следующий URL-адрес для перенаправления:

    http://localhost:3000/callback

  4. Нажмите кнопку Создать новое приложение — созданное OAuth-приложение появится в консоли разработчика, где его можно дополнительно настроить. Quire app list

В итоге у вас должны быть три ключевых параметра:

  • ID клиента для тестового сервера (дев.): :wJoMEodI4fSSR54pfNwIuIzLnaJ
  • Секрет клиента для тестового сервера (дев.): eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex
  • Callback URL: http://localhost:3000/callback

Quire app credentials

Как настроить среду разработки для 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

Сформируйте URL авторизации, на который будете перенаправлять пользователей к OAuth-эндпоинту Quire. Там авторизованные пользователи Quire смогут разрешить приложению доступ к своему контенту.

Пример URL:

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, и приложение должно проверить её. Параметр необязателен, но мы настоятельно рекомендуем его использовать.

Пример URL:

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

Шаг 3. Обработайте ответ OAuth 2.0 сервера

OAuth 2.0 сервер отвечает на запрос доступа вашего приложения, используя URL, указанный в 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 для проверки запроса.

Извлеките код и 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 Обязателен, если вы указывали 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.

Как выполнять API-запросы с токеном доступа Quire?

Теперь у приложения есть токен доступа для выполнения 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.' 
}

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. Хранение секрета клиента в клиентском коде. Секрет клиента — это именно секрет. Если он окажется в бинарнике мобильного приложения или в браузерном бандле, любой сможет его извлечь и подделать ваше приложение. Секрет должен находиться только на сервере под вашим контролем. Если приложение полностью клиентское (SPA, мобильное), используйте OAuth 2.0 PKCE flow вместо встраивания секрета.

2. Пропуск валидации параметра state. Параметр state существует для защиты от CSRF-атак. Если не проверять его в callback, остаётся уязвимость, которую вредоносный сайт может использовать для незаметной привязки аккаунта Quire к сессии злоумышленника. Генерируйте state для каждого запроса, храните в сессии и отклоняйте любой callback, где возвращённый state не совпадает.

3. Отношение к токену доступа как к постоянному. Токены доступа истекают через один час. Приложения, которые сохраняют токен и никогда его не обновляют, прекрасно работают в первый день и тихо ломаются на второй. Реализуйте цикл обновления токенов до запуска, а не как «патч по жалобам пользователей».

4. Опрос API для отслеживания изменений. Опрос расходует лимит запросов, увеличивает задержки и разряжает аккумулятор. Если нужно реагировать на изменения в Quire, используйте вебхуки. Вебхук мгновенно доставит событие к вам — и API-вызов для обнаружения этого события вообще не понадобится.

5. Пропуск списка разрешённых URL-адресов для перенаправления. Каждое OAuth-приложение при регистрации принимает список URL-адресов для перенаправления. Если использовать шаблоны или не настроить его точно, злоумышленник может зарегистрировать свой callback как цель перенаправления и перехватить коды авторизации. Указывайте только те URL-адреса для перенаправления, которые реально используются приложением.

Если вы впервые разрабатываете интеграцию с API, самый быстрый способ освоить паттерны — скопировать готовую интеграцию, например коннектор n8n, и изучить, как в ней реализованы аутентификация, обновление токенов и обработка ошибок.

Когда Quire API не подходит?

Три сценария, когда стоит выбрать другой способ интеграции.

  • Нужно только реагировать на события, а не запрашивать состояние. Вебхуки проще, работают по push-механизму и не требуют авторизации пользователя для подписок только на чтение. Если задача приложения — «уведомить меня, когда что-то произойдёт», используйте вебхуки, а не 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 для традиционных интеграций приложений, а MCP — для интеграций с LLM-агентами.

Что дальше?

Вот полный цикл OAuth 2.0 для Quire API: настройка OAuth-приложения, четыре шага авторизации, использование токена доступа и цикл его обновления. Главная причина, по которой разработчики выпускают работающую интеграцию, которая ломается через два дня, — откладывание реализации цикла обновления «на потом» вместо того, чтобы заложить его с самого начала.

Начните работу в консоли разработчика Quire или изучите полный справочник API. Если вы предпочитаете не писать OAuth-код самостоятельно, сервер Quire MCP возьмёт аутентификацию на себя и станет правильным выбором для интеграций с LLM-агентами. Для интеграций, управляемых событиями, вебхуки обычно подходят лучше, чем паттерн опроса, к которому большинство разработчиков приходит при первом знакомстве с API.

Jimmy Shiau
Software Engineer