Станьте героем: создайте собственное приложение с помощью Quire API

Последнее обновление: 20 июля 2026 г.

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

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

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

Какой способ интеграции с Quire подходит вашему случаю?

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

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

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

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

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

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

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

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

3. Укажите название приложения и URL-адрес для перенаправления. О роли URL-адреса для перенаправления мы поговорим позже, а пока укажите такой адрес:

   http://localhost:3000/callback

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

В итоге у вас должны быть три значения:

• ID клиента для тестового сервера (дев.): :wJoMEodI4fSSR54pfNwIuIzLnaJ
• Секрет клиента для тестового сервера (дев.): eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex
• URL обратного вызова: 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

Сформируйте 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

Пример обработчика обратного вызова:

//...
} 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, в параметрах строки запроса также будут код и параметр 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. Обменяйте код авторизации на access-токен

Приложению нужно выполнить POST-запрос к конечной точке токена с извлечённым кодом авторизации и параметрами запроса из таблицы ниже.

Пример запроса access-токена:

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

Access-токен приходит в ответе в формате JSON.

Пример ответа:

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

Храните токен надёжно и постоянно, так как он нужен для доступа к любому Quire API.

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

Теперь у приложения есть access-токен, с помощью которого можно вызывать API от имени пользователя.

Вызов API

Выполните вызов API, передав access-токен как 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"
}

Как обновить истёкший access-токен Quire API?

Access-токен намеренно рассчитан на краткосрочное использование. Это важный механизм безопасности OAuth 2.0. При потоке Authorization Code Grant access-токены по умолчанию действуют один час.

Когда срок действия access-токена истекает, возвращается HTTP-ошибка 401:

{ 
  code: 401, 
  message: 'Invalid or expired token.'
}

Приложению нужно обновить access-токен.

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 для каждого запроса, храните его в сессии и отклоняйте любой обратный вызов, где возвращённое значение не совпадает.

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

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

5. Нет белого списка URL-адресов для перенаправления. Каждая регистрация OAuth-приложения принимает список 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-клиентом вашего языка.

Как долго действуют access-токены Quire?

По умолчанию access-токен действует один час. Refresh-токены живут дольше и позволяют получать новые access-токены без повторного запроса к пользователю. Встройте цикл обновления токена в приложение с первого дня.

Можно ли использовать Quire API только для чтения?

Да. Области доступа (scopes) OAuth позволяют запрашивать только те разрешения, которые нужны приложению. Если приложение лишь читает задачи, запросите области для чтения. Пользователи Quire увидят запрошенные области на странице авторизации и могут отказать, если запрос кажется избыточным, поэтому лишние запросы снижают конверсию.

Чем отличаются Quire API и сервер Quire MCP?

API это универсальный REST-интерфейс для любого приложения, которое хочет читать или изменять данные Quire от имени пользователя. Сервер MCP создан специально для Claude и других LLM-агентов: он берёт на себя авторизацию, предоставляет стандартную схему инструментов, и вам не нужно писать OAuth-код самостоятельно.

Используйте API для традиционных интеграций приложений, а MCP для интеграций с LLM-агентами.

Что делать дальше?

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

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

Для событийных интеграций вебхуки обычно лучше опроса, к которому приходит большинство первых интеграций с API. А если нужно быстро скриптовать изменения вообще без OAuth-приложения, CLI Quire запускает команды управления проектами прямо из терминала.