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

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

TL;DR: 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 loop 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 resolve isso com OAuth 2.0. Este post percorre a configuração do aplicativo OAuth, o fluxo de autorização em quatro etapas, o loop de token de acesso e refresh, e os erros mais comuns que os desenvolvedores cometem na primeira versão.

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

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

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

Se você está desenvolvendo uma integração de aplicativo típica (app mobile, dashboard web, serviço de sincronização), a API OAuth é o que você precisa. O restante deste post assume 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 autenticado na sua conta do Quire para criar um aplicativo.

1. Acesse o console de 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/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 de desenvolvedor, onde você poderá configurá-lo com mais detalhes.

Em resumo, você deverá 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 o ambiente de desenvolvimento para a API Quire?

Etapa 1. Configure seu aplicativo

Armazene as informações de configuração do aplicativo no seu código.

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 OAuth do Quire. Isso exibirá uma página onde usuários autenticados 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 de Cross-Site Request Forgery (CSRF). Você deve gerar uma string de caracteres aleatória. Ela será retornada 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 em redirect_uri.

Se o usuário aprovar a solicitação de acesso, a resposta conterá um código de autorização. Caso o usuário não aprove 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 for redirecionado de volta para o redirect_uri do seu aplicativo, os parâmetros code e state também estarão presentes na query string. O state é seu token anti-CSRF para validar a requisição.

Extraia o código e o estado dos parâmetros da query string. O estado pode ser validado nesse momento.

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 solicitaçã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 que você recebe na resposta estará em formato JSON.

Exemplo de resposta:

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

Guarde o token com cuidado e de forma permanente, pois você precisará dele para acessar toda a API Quire.

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

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

Chame a API

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

Um exemplo de chamada à 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 Authorization Code Grant Flow, os tokens de acesso têm um tempo de vida padrão de uma hora.

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

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

Seu aplicativo precisará renovar o token de acesso.
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 que os desenvolvedores cometem com a API Quire?

Depois de acompanhar equipes desenvolvendo com a API Quire, os mesmos cinco problemas aparecem repetidamente. Nenhum deles é sutil; todos são evitáveis.

1. Armazenar o client secret em código client-side. O client secret é exatamente isso: um segredo. Se ele acabar num binário de app mobile ou num 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 OAuth 2.0 PKCE em vez de incorporar 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, deixa uma brecha que um site malicioso pode usar para associar silenciosamente uma conta do Quire à sessão do aplicativo de um atacante. Gere o state por requisição, armazene-o na sessão e rejeite qualquer callback em que o state retornado não coincida.

3. Tratar o token de acesso como permanente. Aplicativos que armazenam o token e nunca o renovam funcionam bem no Dia 1 e quebram silenciosamente no Dia 2. Construa o loop de refresh token antes de publicar qualquer coisa, não como uma correção para quando os usuários reclamarem.

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

5. Ignorar a lista de URLs de redirecionamento permitidas. Todo registro de aplicativo OAuth aceita uma lista de URLs de Redirecionamento. Se você usar um wildcard ou não configurá-la com precisão, um atacante pode registrar o próprio callback 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 com a API pela primeira vez, a forma mais rápida de aprender os padrões é fazer um fork de uma integração existente, como a Integração n8n, e estudar como ela 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 optar por 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á desenvolvendo uma integração com Claude ou outro agente de LLM. O servidor MCP do Quire é a superfície certa aqui. Ele cuida da autenticação, vem com um esquema de ferramentas padronizado e elimina a necessidade de escrever código OAuth. O MCP foi criado exatamente para isso; implementar do zero com a API OAuth é mais trabalho para o mesmo resultado.
• Você está fazendo uma exportação pontual de dados. Se você só precisa extrair os dados de um projeto uma única 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 é a 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 Free tier. Limites de taxa se aplicam em 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, então 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 simples em torno do cliente HTTP da sua linguagem seja o padrão mais comum.

Quanto tempo duram os tokens de acesso do Quire?

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 precisar solicitar autorização ao usuário novamente. Incorpore o loop de refresh token ao seu aplicativo desde o Dia 1.

Posso usar a API Quire apenas para leitura?

Sim. Os escopos OAuth permitem solicitar apenas as Permissões que seu aplicativo precisa. Se ele só lê tarefas, solicite escopos de leitura. Os usuários do Quire verão os escopos solicitados na página de autorização e podem recusar se a solicitação parecer excessiva — pedir 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 uso geral para qualquer aplicativo que queira ler ou modificar dados do Quire em nome de um usuário. O servidor MCP foi criado especificamente para Claude e outros agentes de LLM: ele cuida da autenticação, expõe um esquema de ferramentas padronizado e elimina a necessidade de escrever código OAuth. Use a API para integrações de aplicativos tradicionais; use o MCP para integrações com agentes de LLM.

Por onde continuar?

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 loop de refresh. O motivo mais comum pelo qual desenvolvedores publicam uma integração funcional que quebra dois dias depois é tratar o loop de refresh como uma correção posterior, em vez de incorporá-lo desde o Dia 1.

Comece no console de desenvolvedor do Quire ou leia a referência completa da API. Se você 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 com agentes de LLM. Para integrações orientadas a eventos, os Webhooks geralmente são mais adequados do que o padrão de polling que a maioria das integrações de API de primeira vez acaba adotando.