Seja um herói: crie a sua própria aplicação com a API Quire

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

Criar uma aplicação que lê ou modifica os dados de um utilizador do Quire começa com uma decisão: como autenticar sem nunca ver a palavra-passe do utilizador? A API Quire responde com OAuth 2.0.

Este artigo percorre a configuração da aplicação OAuth, o fluxo de autorização em quatro passos, o ciclo de access token e refresh, e as formas mais comuns de os programadores errarem na primeira implementação.

A versão 1.0.0 da OpenAPI do Quire foi lançada em outubro de 2019 e mantém-se estável. Com OAuth, os utilizadores autorizam a sua aplicação a aceder ao conteúdo que têm no Quire (tarefas, projetos, comentários, atribuições, tags, datas limite) e você nunca toca nas credenciais deles.

O utilizador pode revogar esse acesso a qualquer momento sem alterar a palavra-passe. Por isso, as integrações que guardavam palavras-passe eram um antipadrão de segurança, que o OAuth tornou desnecessário.

Que abordagem de integração do Quire se adapta ao seu caso?

Antes de configurar a API OAuth, confirme que a API é mesmo a ferramenta certa. Em 2026, o Quire tem quatro superfícies de integração suportadas, e cada uma resolve um problema diferente.

Se está a criar uma integração de aplicação típica (aplicação móvel, painel web, serviço de sincronização), a API OAuth é o que precisa. O resto deste artigo assume que segue por esse caminho.

Como configurar uma aplicação OAuth para a API Quire?

Para usar a API Quire, terá de criar uma aplicação OAuth.

Crie a sua aplicação OAuth do Quire

Tem de ter sessão iniciada na sua conta Quire para criar uma aplicação.

1. Aceda à consola de aplicações para programadores do Quire e clique no botão Criar nova aplicação.

2. Escolha a organização Quire a que a sua aplicação pertence. Os membros da organização podem ver e editar todas as aplicações que pertencem à organização selecionada.

3. Dê um nome à sua aplicação e indique um URL de Redirecionamento. Falaremos mais à frente da função do URL de Redirecionamento. Por agora, pode usar o seguinte URL:

   http://localhost:3000/callback

4. Clique no botão Criar nova aplicação. A aplicação OAuth acabada de criar surge na página da consola, onde pode configurá-la com mais detalhe.

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

Passo 1. Configure a sua aplicação

Guarde na sua aplicação a informação de configuração.

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

Passo 2. Redirecione o utilizador para autorizar a aplicação no Quire

Gere um URL de autorização para o qual vai redirecionar os utilizadores, apontando para o endpoint OAuth do Quire. Isto mostra uma página web onde os utilizadores do Quire com sessão iniciada podem autorizar a sua aplicação a aceder ao seu conteúdo.

URL de exemplo:

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

Um exemplo de vista com a ligação 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 cadeia aleatória usada para evitar ataques de Cross-Site Request Forgery (CSRF). Deve gerar uma cadeia de caracteres aleatória, que será devolvida à sua aplicação, inalterada, no Passo 3. A sua aplicação deve validar este valor. Embora seja opcional, recomendamos vivamente incluir este parâmetro.

URL de exemplo:

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

Passo 3. Trate a resposta do servidor OAuth 2.0

O servidor OAuth 2.0 responde ao pedido de acesso da sua aplicação através do URL indicado em redirect_uri.

Se o utilizador aprovar o pedido 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 se mostra 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 utilizador é redirecionado de volta para o redirect_uri da sua aplicação, os parâmetros code e state também estão presentes na query string. O state é o seu token anti-falsificação CSRF para validar o pedido.

Extraia o code e o state dos parâmetros da query string. Nesta fase, 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);
     });
}

Passo 4. Troque o código de autorização por um access token

A sua aplicação tem de fazer uma chamada POST ao endpoint de token com o código de autorização extraído e os parâmetros de pedido indicados abaixo.

Um exemplo de pedido 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 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 precisa dele para aceder a qualquer API Quire.

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

A sua aplicação já tem um access token que pode ser usado para fazer chamadas à API em nome do utilizador.

Chame a API

Faça a chamada à API passando o access token como bearer token no cabeçalho do pedido.

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 access token expirado da API Quire?

Um access token destina-se, de propósito, a uso de curta duração. É um mecanismo de segurança importante do OAuth 2.0. No Authorization Code Grant Flow, os access tokens têm por predefinição uma duração de uma hora.

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

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

A sua aplicação terá de 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))
          });
    });
}

Em alternativa, a sua aplicação pode redirecionar o utilizador para o fluxo de autenticação.

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

Depois de acompanhar equipas a desenvolver sobre a API Quire, os mesmos cinco problemas repetem-se. Nenhum é subtil, 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 acabar num binário de aplicação móvel ou num bundle de browser, qualquer pessoa o pode extrair e fazer-se passar pela sua aplicação.

O segredo deve viver apenas num servidor que controle. Se a aplicação for puramente do lado do cliente (single-page app, móvel), use o fluxo OAuth 2.0 PKCE em vez de embutir o segredo.

2. Esquecer-se de validar o parâmetro state. O parâmetro state existe para evitar ataques CSRF. Se não o validar no callback, deixa uma brecha que um site malicioso pode usar para associar, em silêncio, uma conta Quire à sessão de uma aplicação do atacante.

Gere o state por pedido, guarde-o na sessão e rejeite qualquer callback cujo state devolvido não coincida.

3. Tratar o access token como permanente. Os access tokens expiram ao fim de uma hora. As aplicações que guardam o token e nunca o renovam funcionam bem no Dia 1 e deixam de funcionar, sem aviso, no Dia 2.

Construa o ciclo de refresh token antes de lançar o que quer que seja, e não como um remendo do tipo «corrige-se quando os utilizadores se queixarem».

4. Fazer polling à API para detetar alterações. O polling gasta limite de pedidos, aumenta a latência e consome bateria. Se precisa de reagir a alterações no Quire, use antes webhooks.

O webhook envia-lhe o evento de imediato, e a chamada à API que teria feito para detetar esse evento nunca chega a ser necessária.

5. Ignorar a lista de URLs de redirecionamento permitidos. Cada registo de aplicação OAuth aceita uma lista de URLs de redirecionamento. Se usar um wildcard ou não a configurar com precisão, um atacante pode registar o callback dele como destino de redirecionamento e intercetar códigos de autorização.

Adicione apenas os URLs exatos que a sua aplicação realmente usa.

Se vai usar 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 trata a autenticação, a renovação e os estados de erro.

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

Há três situações em que deve recorrer a outra superfície de integração.

• Só precisa de reagir a eventos, não de consultar o estado. Os webhooks são mais simples, baseados em push, e não exigem autorização do utilizador para subscrições de eventos só de leitura. Se a função da sua aplicação é «avisa-me quando algo acontecer», use webhooks, não a API.
• Está a criar uma integração com o Claude ou com um agente LLM. O servidor MCP do Quire é a superfície certa aqui. Trata da autenticação, traz um esquema padrão e dispensa-o de escrever código OAuth. O MCP foi concebido para isto, e construir a sua própria solução com a API OAuth dá mais trabalho para o mesmo resultado.
• Está a fazer uma exportação de dados pontual. Se só precisa de extrair os dados de um projeto uma vez, para análise ou cópia de segurança, a integração n8n ou uma exportação CSV manual poupa-lhe uma semana de desenvolvimento.

Se nenhuma destas situações se aplica, a API OAuth é a sua ferramenta.

Perguntas frequentes

A API Quire exige uma assinatura paga do Quire?

Não. A API Quire está disponível em todos os planos, incluindo o nível gratuito. Aplicam-se limites de pedidos em todos os planos; consulte a documentação da API para ver os limites atuais por aplicação.

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

A API é baseada em HTTP, com corpos de pedido e de resposta em JSON, pelo que funciona qualquer linguagem com um cliente HTTP e um analisador de JSON. Os exemplos deste artigo são em JavaScript, mas o mesmo fluxo funciona de forma idêntica em Python, Go, Ruby, PHP e qualquer outra linguagem.

Não existe uma biblioteca cliente oficial. A superfície da API é pequena o suficiente para que o padrão habitual seja um wrapper simples à volta do cliente HTTP da sua linguagem.

Quanto tempo duram os access tokens do Quire?

Os access tokens expiram ao fim de uma hora por predefinição. Os refresh tokens duram mais e permitem obter novos access tokens sem voltar a pedir autorização ao utilizador. Integre o ciclo de refresh token na sua aplicação desde o Dia 1.

Posso usar a API Quire apenas para leitura?

Sim. Os âmbitos (scopes) OAuth permitem pedir apenas as permissões de que a sua aplicação precisa. Se a aplicação só lê tarefas, peça âmbitos de leitura. Os utilizadores do Quire veem os âmbitos pedidos na página de autorização e podem recusar se o pedido parecer excessivo, por isso pedir de mais 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 aplicação que queira ler ou modificar dados do Quire em nome de um utilizador. O servidor MCP foi concebido para o Claude e outros agentes LLM: trata da autenticação, expõe um esquema de ferramentas padrão e dispensa-o de escrever código OAuth.

Use a API para integrações de aplicações tradicionais; use o MCP para integrações com agentes LLM.

E agora, por onde seguir?

Este é o fluxo OAuth 2.0 completo da API Quire: configuração da aplicação OAuth, autorização em quatro passos, utilização do access token e ciclo de renovação. A razão mais comum para uma integração que funciona ser lançada e falhar dois dias depois é tratar o ciclo de renovação como uma correção posterior, em vez de o integrar desde o Dia 1.

Comece na consola de aplicações para programadores do Quire ou leia a referência completa da API. Se prefere não escrever código OAuth, o servidor MCP do Quire trata da autenticação por si e é a escolha certa para integrações com agentes LLM.

Para integrações orientadas a eventos, os webhooks costumam ser mais adequados do que o padrão de polling em que acabam muitas primeiras integrações com a API. E se só quer executar alterações rápidas por script, sem criar uma aplicação OAuth, a CLI do Quire executa comandos de gestão de projetos diretamente no terminal.