Seja um herói: crie seu próprio aplicativo com a API Quire

Última atualização: 20 de julho de 2026

Criar um aplicativo que lê ou modifica os dados de um usuário do Quire começa por uma decisão: como autenticar sem nunca ver a senha do usuário? A API Quire responde com OAuth 2.0. Este post mostra a configuração do aplicativo OAuth, o fluxo de autorização em quatro etapas, o ciclo de access token e refresh, e as formas mais comuns de errar 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 OAuth, os usuários autorizam seu aplicativo a acessar o conteúdo deles no Quire (tarefas, projetos, comentários, atribuições, tags, datas limite) e você nunca toca nas credenciais. O usuário pode revogar o acesso a qualquer momento sem trocar a senha, e por isso integrações que guardavam senhas eram um antipadrão de segurança, até o OAuth tornar isso desnecessário.

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

Antes de montar a API OAuth, confirme se ela é mesmo a ferramenta certa. O Quire tem quatro superfícies de integração compatíveis em 2026, e cada uma resolve um problema diferente.

Se você está criando uma integração típica de aplicativo (app mobile, painel web, serviço de sincronização), a API OAuth é o que você quer. O restante deste post parte desse caminho.

Como configurar um aplicativo OAuth para a API Quire?

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

Crie seu aplicativo OAuth do Quire

Você precisa estar logado na sua conta Quire para criar um aplicativo.

1. Acesse o console de aplicativos para desenvolvedores 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 podem ver e editar todos os aplicativos da organização selecionada.

3. Dê um nome ao aplicativo e informe uma URL de Redirecionamento. Vamos falar do 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. O aplicativo OAuth recém-criado aparecerá na página do console de desenvolvedor, onde você poderá configurá-lo melhor.

Em resumo, você deve 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

Guarde as informações de configuração no seu aplicativo.

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. Ele exibe uma página web em que usuários logados no Quire podem 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 view com o 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 evitar ataques de Cross-Site Request Forgery (CSRF). Gere uma sequência 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 em redirect_uri.

Se o usuário aprovar a solicitação de acesso, a resposta contém um código de autorização. Se não aprovar, a resposta contém uma mensagem de erro. O código de autorização ou a mensagem de erro devolvidos ao servidor web aparecem na query string, como 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, os parâmetros code e state também estarão presentes na query string. O state é o seu token anti-CSRF para validar a requisição.

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

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 access token

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 access token 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 access token que você recebe na resposta vem 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ê precisa dele para acessar qualquer API do Quire.

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

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

Chame a API

Faça a chamada de API enviando o access token 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 access token expirado da API Quire?

Um access token é feito de propósito para uso de curto prazo. Esse é um importante mecanismo de segurança do OAuth 2.0. No fluxo Authorization Code Grant, os access tokens têm duração de uma hora por padrão.

Quando um access token expira, um erro HTTP 401 é retornado:

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

Seu aplicativo precisará renovar o 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 ao usar a API Quire?

Depois de acompanhar equipes que criam sobre a API Quire, os mesmos cinco problemas se repetem. Nenhum é sutil, e todos são evitáveis.

1. Guardar o client secret em código do lado do cliente. O client secret é exatamente isso: um segredo. Se ele for parar no binário de um app mobile ou em um bundle de navegador, qualquer pessoa pode extraí-lo e se passar pelo seu aplicativo.

O secret deve ficar apenas em um servidor sob seu controle. Se seu aplicativo é puramente client-side (single-page app, mobile), use o fluxo OAuth 2.0 PKCE em vez de embutir o secret.

2. Esquecer de validar o parâmetro state. O parâmetro state existe para evitar ataques CSRF. Se você pula a validação no callback, deixa uma brecha que um site malicioso pode usar para associar, sem você notar, uma conta Quire à sessão de aplicativo de um invasor. Gere o state a cada requisição, guarde-o na sessão e rejeite qualquer callback cujo state devolvido não corresponda.

3. Tratar o access token como permanente. Os access tokens expiram após uma hora. Aplicativos que guardam o token e nunca o renovam funcionam bem no primeiro dia e quebram em silêncio no segundo. Construa o ciclo de refresh token antes de lançar qualquer coisa, e não como um remendo de "conserto quando os usuários reclamarem".

4. Fazer polling na API para detectar mudanças. O polling consome limite de requisições, aumenta a latência e gasta bateria. Se você precisa reagir a mudanças no Quire, use webhooks. O webhook envia o evento a você na hora, e a chamada de API que você faria para detectá-lo 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ê usa curinga ou deixa de configurá-la com precisão, um invasor pode registrar o callback dele como destino de redirecionamento e interceptar códigos de autorização. Adicione apenas as URLs exatas que seu aplicativo realmente usa.

Se você está criando sobre 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 do n8n, e estudar como ela trata autenticação, refresh e estados de erro.

Quando a API Quire não é a melhor opção?

Três situações em que vale buscar outra superfície de integração.

• 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á criando uma integração com o Claude ou com um agente de LLM. O servidor MCP do Quire é a superfície certa aqui. Ele cuida da autenticação, traz um esquema padrão e evita que você escreva código OAuth. O MCP foi feito para isso, e montar a sua própria solução com a API OAuth dá mais trabalho para o mesmo resultado.
• Você vai fazer uma exportação de dados pontual. Se 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 economiza uma semana de desenvolvimento.

Se nenhuma dessas situações 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, inclusive no gratuito. Os limites de requisições valem para todos os planos. Consulte a documentação da API para ver 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 funciona qualquer linguagem com cliente HTTP e parser de JSON. Os exemplos deste 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 bastante para que um wrapper simples em torno do cliente HTTP da sua linguagem seja o padrão comum.

Quanto tempo duram os access tokens do Quire?

Os access tokens expiram após uma hora por padrão. Os refresh tokens duram mais e servem para obter novos access tokens sem pedir autorização ao usuário de novo. Construa o ciclo de refresh token no seu aplicativo desde o primeiro dia.

Posso usar a API Quire só para leitura?

Sim. Os escopos OAuth permitem solicitar somente as permissões de que seu aplicativo precisa. Se ele só lê tarefas, solicite escopos de leitura. Os usuários do Quire veem os escopos solicitados na página de autorização e podem recusar se o pedido parecer excessivo, então pedir demais 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 para o Claude e outros agentes de LLM: cuida da autenticação, expõe um esquema de ferramentas padrão e evita que você escreva código OAuth. Use a API para integrações tradicionais de aplicativos e o MCP para integrações com agentes de LLM.

Para onde ir daqui?

Esse é o fluxo OAuth 2.0 completo da API Quire: configuração do aplicativo OAuth, autorização em quatro etapas, uso do access token e ciclo de renovação. O motivo mais comum para uma integração funcionar e quebrar dois dias depois é tratar o ciclo de refresh como correção para depois, em vez de construí-lo desde o primeiro dia.

Comece no console de aplicativos para desenvolvedores do Quire ou leia a referência completa da API. Se prefere 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 costumam ser mais adequados que o padrão de polling em que muitas primeiras integrações com a API acabam. E se você só quer executar alterações rápidas por script, sem criar um aplicativo OAuth, a CLI do Quire executa comandos de gerenciamento de projetos direto do seu terminal.