Seja um Herói: Crie Seu Próprio Aplicativo com a API Quire

Última atualização: 28 de maio de 2026

Resumo: A API OAuth 2.0 do Quire permite que seu aplicativo atue na conta Quire de um usuário sem armazenar a senha dele. Você precisará de um aplicativo OAuth registrado (ID do cliente, segredo, URL de Redirecionamento), um fluxo de autorização em quatro etapas (configurar, redirecionar, tratar resposta, trocar código por token) e um ciclo de refresh token, pois os tokens de acesso expiram após uma hora.

Criar um aplicativo que lê ou modifica dados do Quire de um usuário começa com uma decisão: como autenticar sem nunca ver a senha do usuário? A API Quire responde isso com o OAuth 2.0. Este post percorre a configuração do aplicativo OAuth, o fluxo de autorização em quatro etapas, o ciclo de token de acesso e refresh, e as formas mais comuns pelas quais os desenvolvedores erram na primeira implementação.

A versão 1.0.0 da OpenAPI do Quire foi lançada em outubro de 2019 e permanece estável. Com o OAuth, os usuários autorizam seu aplicativo a acessar o conteúdo deles no Quire (tarefas, projetos, comentários, atribuições, tags, datas limite) sem que você toque nas credenciais deles. O usuário pode revogar esse acesso a qualquer hora sem alterar a senha — é por isso que integrações que armazenavam senhas eram um antipadrão de segurança antes que o OAuth as tornasse desnecessárias.

Qual abordagem de integração do Quire se encaixa no seu caso de uso?

Antes de configurar a API OAuth, certifique-se de que a API é realmente a ferramenta certa. O Quire possui quatro superfícies de integração suportadas em 2026, e cada uma resolve problemas diferentes.

Se você está construindo uma integração típica de aplicativo (aplicativo móvel, painel web, serviço de sincronização), a API OAuth é o que você precisa. O restante deste post pressupõe que você está nesse caminho.

Como configurar um aplicativo OAuth para a API Quire?

Para usar a API Quire, você precisará criar um aplicativo OAuth.

Crie seu aplicativo OAuth no Quire

Você precisará estar logado na sua conta do Quire para criar um aplicativo.

1. Acesse o console de aplicativos do desenvolvedor do Quire e clique no botão Criar novo aplicativo.

2. Escolha a Organização Quire à qual seu aplicativo pertence; os membros da organização poderão visualizar e editar todos os aplicativos pertencentes à organização selecionada.

3. Dê um nome ao seu aplicativo e informe a URL de Redirecionamento; vamos discutir o papel da URL de Redirecionamento mais adiante. Por ora, você pode usar a seguinte URL:

   http://localhost:3000/callback

4. Clique no botão Criar novo aplicativo — seu novo aplicativo OAuth será exibido na página do console do desenvolvedor, onde você poderá configurá-lo.

Em resumo, você terá estas três informações:

• ID do Cliente de Desenvolvimento: :wJoMEodI4fSSR54pfNwIuIzLnaJ
• Segredo do Cliente de Desenvolvimento: eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex
• URL de Callback: http://localhost:3000/callback

Como configurar seu ambiente de desenvolvimento para a API Quire?

Etapa 1. Configure seu aplicativo

Armazene as informações de configuração do seu aplicativo dentro dele.

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';

Etapa 2. Redirecione o usuário para autorizar o aplicativo no Quire

Gere uma URL de autorização para redirecionar seus usuários ao endpoint URI OAuth do Quire. Isso exibirá uma página web onde os usuários logados no Quire poderão autorizar seu aplicativo a acessar o conteúdo deles.

URL de exemplo:

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

Um exemplo de link de autorização pode ser assim:

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

O parâmetro state é uma string aleatória usada para prevenir ataques CSRF (Cross-Site Request Forgery). Você deve gerar uma string de caracteres aleatória. Ela será devolvida ao seu aplicativo, sem alterações, na Etapa 3. Seu aplicativo deve validar esse valor. Embora seja opcional, recomendamos fortemente incluir esse parâmetro.

URL de exemplo:

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

Etapa 3. Trate a resposta do servidor OAuth 2.0

O servidor OAuth 2.0 responde à solicitação de acesso do seu aplicativo usando a URL especificada no redirect_uri.

Se o usuário aprovar a solicitação de acesso, a resposta conterá um código de autorização. Se o usuário não aprovar a solicitação, a resposta conterá uma mensagem de erro. O código de autorização ou a mensagem de erro retornado ao servidor web aparece na query string, conforme mostrado abaixo:

Uma resposta de erro:

http://localhost:3000/callback?error=access_denied

Uma resposta com código de autorização:

http://localhost:3000/callback?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Um exemplo de callback pode ser assim:

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

Quando o usuário é redirecionado de volta para o redirect_uri do seu aplicativo, um parâmetro code e um parâmetro state também estarão presentes na query string. O state é seu token anti-falsificação CSRF para validar a requisição.

Extraia o code e o state dos parâmetros da query string. O state pode ser validado nesse ponto.

Um exemplo de validação pode ser assim:

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

Etapa 4. Troque o código de autorização pelo token de acesso

Seu aplicativo precisa fazer uma chamada POST ao endpoint de token com o código de autorização extraído e os parâmetros de requisição abaixo.

Um exemplo de requisição de token de acesso pode ser assim:

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

O token de acesso recebido na resposta estará em formato JSON.

Exemplo de resposta:

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

O token deve ser guardado com cuidado e de forma permanente, pois você precisará dele para acessar toda a API Quire.

Como fazer chamadas de API com o token de acesso do Quire?

Seu aplicativo agora tem um token de acesso que pode ser usado para fazer chamadas de API em nome do usuário.

Chamando a API

Faça a chamada de API passando o token de acesso como bearer token no cabeçalho da requisição.

Um exemplo de chamada de API pode ser assim:

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

Exemplo de resposta:

{
  "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"
}

Como renovar um token de acesso expirado da API Quire?

Um token de acesso é intencionalmente projetado para uso de curto prazo. Esse é um mecanismo de segurança importante do OAuth 2.0. Ao usar o Fluxo de Concessão de Código de Autorização, os tokens de acesso têm uma vida útil padrão de uma hora.

Quando um token de acesso expira, um erro HTTP 401 será retornado:

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

Como alternativa, seu aplicativo pode redirecionar o usuário para o fluxo de autenticação.

Quais são os erros mais comuns dos desenvolvedores com a API Quire?

Depois de acompanhar equipes construindo contra a API Quire, os mesmos cinco problemas se repetem. Nenhum é sutil; todos são evitáveis.

1. Armazenar o segredo do cliente em código client-side. O segredo do cliente é exatamente isso: um segredo. Se ele acabar em um binário de aplicativo móvel ou em um bundle de navegador, qualquer pessoa pode extraí-lo e se passar pelo seu aplicativo. O segredo deve existir apenas em um servidor que você controla. Se seu aplicativo é puramente client-side (single-page app, mobile), use o fluxo PKCE do OAuth 2.0 em vez de embutir o segredo.

2. Esquecer de validar o parâmetro state. O parâmetro state existe para prevenir ataques CSRF. Se você pular a validação no callback, deixará uma brecha que um site malicioso pode usar para associar silenciosamente uma conta Quire à sessão do aplicativo de um atacante. Gere o state por requisição, armazene-o na sessão e rejeite qualquer callback onde o state retornado não corresponda.

3. Tratar o token de acesso como permanente. Os tokens de acesso expiram após uma hora. Aplicativos que armazenam o token e nunca o renovam funcionam bem no Dia 1 e quebram silenciosamente no Dia 2. Construa o ciclo de refresh token antes de lançar qualquer coisa — não como um patch de "corrigir quando os usuários reclamarem".

4. Fazer polling da API para detectar mudanças. O polling consome limite de taxa, aumenta a latência e drena a bateria. Se você precisa reagir a mudanças no Quire, use webhooks. O webhook entrega o evento para você instantaneamente; a chamada de API que você teria feito para detectar esse evento nunca precisa acontecer.

5. Ignorar a lista de permissões de URL de Redirecionamento. Todo registro de aplicativo OAuth aceita uma lista de URLs de Redirecionamento. Se você usar wildcard ou pular a configuração precisa, um atacante pode registrar o callback dele como seu destino de redirecionamento e interceptar códigos de autorização. Adicione apenas as URLs exatas que seu aplicativo realmente usa.

Se você está desenvolvendo contra a API pela primeira vez, a forma mais rápida de aprender os padrões é fazer um fork de uma integração existente, como o conector n8n, e estudar como ele trata autenticação, refresh e estados de erro.

Quando a API Quire não é a escolha certa?

Três situações em que você deve usar uma superfície de integração diferente.

• Você só precisa reagir a eventos, não consultar estado. Os Webhooks são mais simples, baseados em push e não exigem autorização do usuário para assinaturas de eventos somente leitura. Se a função do seu aplicativo é "me avise quando algo acontecer", use webhooks, não a API.
• Você está construindo uma integração com Claude ou outro agente LLM. O servidor MCP do Quire é a superfície certa aqui. Ele gerencia a autenticação, disponibiliza um esquema padrão e dispensa a escrita de código OAuth. O MCP foi criado exatamente para isso; implementar sua própria solução com a API OAuth dá mais trabalho pelo mesmo resultado.
• Você está fazendo uma exportação de dados pontual. Se você só precisa extrair os dados de um projeto uma vez para análise ou backup, a integração n8n ou uma exportação manual em CSV vai economizar uma semana de desenvolvimento.

Se nenhum desses casos se aplica, a API OAuth é sua ferramenta.

Perguntas Frequentes

A API Quire exige um plano pago do Quire?

Não. A API Quire está disponível em todos os planos, incluindo o nível gratuito. Limites de taxa se aplicam a todos os planos; consulte a documentação da API para os limites atuais por aplicativo.

Quais linguagens de programação a API Quire suporta?

A API é baseada em HTTP com corpos de requisição e resposta em JSON, portanto qualquer linguagem com um cliente HTTP e um parser JSON funciona. Os exemplos neste post são em JavaScript, mas o mesmo fluxo funciona de forma idêntica em Python, Go, Ruby, PHP e qualquer outra linguagem. Não há biblioteca cliente oficial; a superfície da API é pequena o suficiente para que um wrapper fino em torno do cliente HTTP da sua linguagem seja o padrão comum.

Por quanto tempo os tokens de acesso do Quire são válidos?

Os tokens de acesso expiram após uma hora por padrão. Os refresh tokens duram mais e podem ser usados para obter novos tokens de acesso sem solicitar a autenticação do usuário novamente. Inclua o ciclo de refresh token no seu aplicativo desde o Dia 1.

Posso usar a API Quire apenas para leitura?

Sim. Os escopos OAuth permitem que você solicite apenas as permissões que seu aplicativo precisa. Se o seu aplicativo apenas lê tarefas, solicite escopos de leitura. Os usuários do Quire verão os escopos solicitados na página de autorização e poderão recusar se a solicitação parecer excessiva, portanto solicitar mais do que o necessário prejudica a conversão.

Qual é a diferença entre a API Quire e o servidor MCP do Quire?

A API é uma superfície REST de propósito geral para qualquer aplicativo que queira ler ou modificar dados do Quire em nome de um usuário. O servidor MCP é desenvolvido especificamente para o Claude e outros agentes LLM: ele gerencia a autenticação, expõe um esquema de ferramentas padrão e dispensa a escrita de código OAuth. Use a API para integrações de aplicativos tradicionais; use o MCP para integrações de agentes LLM.

Qual é o próximo passo?

Esse é o fluxo OAuth 2.0 completo para a API Quire: configuração do aplicativo OAuth, autorização em quatro etapas, uso do token de acesso e o ciclo de refresh. O motivo mais comum pelo qual desenvolvedores lançam uma integração funcional que quebra dois dias depois é tratar o ciclo de refresh como uma correção futura em vez de construí-lo desde o Dia 1.

Comece pelo console de aplicativos do desenvolvedor Quire ou leia a referência completa da API. Se preferir não escrever código OAuth, o servidor MCP do Quire cuida da autenticação por você e é a escolha certa para integrações de agentes LLM. Para integrações baseadas em eventos, os webhooks geralmente se encaixam melhor do que o padrão de polling que a maioria das integrações de API de primeira viagem acaba adotando.