developers · Oct 1, 2019

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

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

Quire API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  3. Укажите имя приложения и URL-адрес для перенаправления — о его роли поговорим чуть ниже. Пока можно подставить такой адрес:

    http://localhost:3000/callback

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

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

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

Учётные данные приложения Quire

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

Сгенерируйте ссылку, по которой пользователь будет перенаправлен на 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 — это случайная строка для защиты от атак Cross-Site Request Forgery (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 — это ваш anti-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-запрос на token-эндпоинт с извлечённым кодом авторизации и параметрами, перечисленными ниже.

Параметр Значение
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

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

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

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

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

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

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

Когда Quire API — не лучший выбор?

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

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

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

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

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

В чём разница между Quire API и MCP-сервером Quire?

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

Куда двигаться дальше?

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

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

Jimmy Shiau
Software Engineer