Diventa un eroe: crea la tua app con Quire API

Ultimo aggiornamento: 20 luglio 2026

Creare un'app che legge o modifica i dati Quire di un utente parte da una decisione: come autenticare senza mai vedere la password dell'utente? Quire API risponde con OAuth 2.0. Questo articolo illustra la configurazione dell'app OAuth, il flusso di autorizzazione in quattro passaggi, il ciclo access token e refresh token, e gli errori più comuni alla prima implementazione.

La versione 1.0.0 di OpenAPI di Quire è uscita a ottobre 2019 ed è rimasta stabile. Con OAuth, gli utenti autorizzano la tua app ad accedere ai loro contenuti Quire (attività, progetti, commenti, assegnazioni, etichette, date di scadenza) e tu non tocchi mai le loro credenziali.

L'utente può revocare l'accesso in qualsiasi momento senza cambiare password. Per questo, prima di OAuth, le integrazioni che salvavano le password erano un antipattern di sicurezza.

Quale approccio di integrazione con Quire fa per te?

Prima di configurare l'API OAuth, assicurati che sia lo strumento giusto. Nel 2026 Quire offre quattro superfici di integrazione supportate, e risolvono problemi diversi.

Se stai creando una tipica integrazione di app (app mobile, cruscotto web, servizio di sincronizzazione), l'API OAuth è quello che fa per te. Il resto dell'articolo presume che tu sia su questa strada.

Come si configura un'app OAuth per Quire API?

Per usare Quire API devi creare un'app OAuth.

Crea la tua app OAuth di Quire

Per creare un'app devi aver effettuato l'accesso al tuo account Quire.

1. Vai alla console per sviluppatori di Quire e clicca sul pulsante Crea nuova app.

2. Scegli l'Organizzazione Quire a cui appartiene la tua app: i membri dell'organizzazione possono visualizzare e modificare tutte le app che appartengono all'organizzazione selezionata.

3. Assegna un nome alla tua applicazione e indica un URL di redirezione: ne vedremo il ruolo più avanti. Per ora puoi usare il seguente URL:

   http://localhost:3000/callback

4. Clicca sul pulsante Crea nuova app: la tua nuova applicazione OAuth comparirà nella pagina della console per sviluppatori, dove potrai configurarla ulteriormente.

In sintesi, dovresti avere queste tre informazioni:

• Client ID di Sviluppo: :wJoMEodI4fSSR54pfNwIuIzLnaJ
• Client Secret di Sviluppo: eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex
• URL di callback: http://localhost:3000/callback

Come si prepara l'ambiente di sviluppo per Quire API?

Passaggio 1. Configura la tua app

Inserisci nella tua app le informazioni di configurazione dell'applicazione.

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

Passaggio 2. Reindirizza l'utente per autorizzare l'app su Quire

Genera un URL di autorizzazione verso cui reindirizzare i tuoi utenti, cioè l'endpoint OAuth di Quire. Verrà mostrata una pagina web in cui gli utenti Quire connessi possono autorizzare la tua applicazione ad accedere ai loro contenuti.

URL di esempio:

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

Una vista del link di autorizzazione potrebbe essere questa:

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

Il parametro state è una stringa casuale usata per prevenire gli attacchi Cross-Site Request Forgery (CSRF). Devi generare una stringa di caratteri casuale. Ti verrà restituita invariata nel Passaggio 3, e la tua applicazione deve convalidarne il valore. È facoltativo, ma consigliamo vivamente di includerlo.

URL di esempio:

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

Passaggio 3. Gestisci la risposta del server OAuth 2.0

Il server OAuth 2.0 risponde alla richiesta di accesso della tua applicazione usando l'URL indicato in redirect_uri.

Se l'utente approva la richiesta di accesso, la risposta contiene un codice di autorizzazione. Se non la approva, la risposta contiene un messaggio di errore. Il codice di autorizzazione o il messaggio di errore restituito al server web compare nella query string, come mostrato di seguito:

Una risposta di errore:

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

Una risposta con codice di autorizzazione:

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

Un esempio di callback potrebbe essere:

//...
} 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 l'utente viene reindirizzato al redirect_uri della tua applicazione, nei parametri della query string saranno presenti anche un codice e il parametro state. Lo state è il tuo token anti-contraffazione CSRF per convalidare la richiesta.

Estrai il codice e lo state dai parametri della query string. A questo punto puoi convalidare lo state.

Un esempio di convalida potrebbe essere:

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

Passaggio 4. Scambia il codice di autorizzazione con l'access token

La tua applicazione deve effettuare una chiamata POST all'endpoint del token con il codice di autorizzazione estratto e i parametri di richiesta indicati qui sotto.

Un esempio di richiesta dell'access token potrebbe essere questo:

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

L'access token che ricevi in risposta sarà in formato JSON.

Esempio di risposta:

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

Il token va conservato con cura e in modo permanente, perché ti serve per accedere a ogni Quire API.

Come si effettuano le chiamate API con l'access token di Quire?

La tua app ora ha un access token che può essere usato per effettuare chiamate API per conto dell'utente.

Chiama l'API

Effettua la chiamata API passando l'access token come bearer token nell'header della richiesta.

Un esempio di chiamata API potrebbe essere:

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

Esempio di risposta:

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

Come si aggiorna un access token di Quire API scaduto?

Un access token è pensato di proposito per un uso a breve termine. È un importante meccanismo di sicurezza di OAuth 2.0. Con l'Authorization Code Grant Flow, gli access token hanno per impostazione predefinita una durata di un'ora.

Quando un access token scade, viene restituito un errore HTTP 401:

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

La tua applicazione dovrà aggiornare l'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))
          });
    });
}

In alternativa, la tua applicazione può reindirizzare l'utente al flusso di autenticazione.

Quali sono gli errori più comuni degli sviluppatori con Quire API?

Dopo aver visto molti team lavorare con Quire API, gli stessi cinque problemi si ripetono. Nessuno è sottile; tutti si possono evitare.

1. Conservare il client secret nel codice lato client. Il client secret è proprio questo: un segreto. Se finisce nel binario di un'app mobile o in un bundle del browser, chiunque può estrarlo e impersonare la tua app. Il secret deve stare solo su un server che controlli. Se la tua app è solo lato client (single-page app, mobile), usa invece il flusso OAuth 2.0 PKCE.

2. Dimenticare di convalidare il parametro state. Il parametro state serve a prevenire gli attacchi CSRF. Se salti la convalida nella callback, lasci una falla che un sito malevolo può usare per associare in silenzio un account Quire alla sessione dell'app di un aggressore. Genera state a ogni richiesta, salvalo nella sessione e rifiuta ogni callback in cui lo state restituito non corrisponde.

3. Trattare l'access token come permanente. Gli access token scadono dopo un'ora. Le app che salvano il token e non lo aggiornano mai funzionano bene il primo giorno e si rompono in silenzio il secondo. Costruisci il ciclo del refresh token prima di rilasciare qualsiasi cosa, non come una patch del tipo «sistemiamo quando gli utenti si lamentano».

4. Fare polling dell'API per rilevare i cambiamenti. Il polling consuma limiti di frequenza, latenza e batteria. Se devi reagire ai cambiamenti in Quire, usa invece i Webhooks. Il webhook ti invia l'evento all'istante; la chiamata API che avresti fatto per rilevarlo non serve più.

5. Saltare la lista consentita degli URL di redirezione. Ogni registrazione di un'app OAuth accetta un elenco di URL di redirezione. Se usi un carattere jolly o non lo configuri con precisione, un aggressore può registrare la sua callback come destinazione di redirezione e intercettare i codici di autorizzazione. Aggiungi solo gli URL esatti che la tua app usa davvero.

Se è la prima volta che lavori con l'API, il modo più rapido per imparare gli schemi è fare un fork di un'integrazione esistente come il connettore n8n e studiare come gestisce autenticazione, refresh e stati di errore.

Quando Quire API non è la scelta giusta?

Tre situazioni in cui conviene scegliere un'altra superficie di integrazione.

• Ti basta reagire agli eventi, non interrogare lo stato. I Webhooks sono più semplici, basati su push e non richiedono l'autorizzazione dell'utente per le sottoscrizioni a eventi in sola lettura. Se il compito della tua app è «avvisami quando succede qualcosa», usa i webhook, non l'API.
• Stai creando un'integrazione con Claude o con un agente LLM. Il server Quire MCP è la superficie giusta. Gestisce l'autenticazione, include uno schema standard e ti evita di scrivere codice OAuth. MCP è nato per questo; costruire tutto con l'API OAuth è più lavoro per lo stesso risultato.
• Devi fare un'esportazione di dati una tantum. Se ti serve solo estrarre una volta i dati di un progetto per un'analisi o un backup, l'integrazione n8n o un'esportazione CSV manuale ti farà risparmiare una settimana di sviluppo.

Se nessuna di queste situazioni ti riguarda, l'API OAuth è lo strumento giusto.

Domande frequenti

Quire API richiede un piano Quire a pagamento?

No. Quire API è disponibile su ogni piano, compreso quello gratuito. Su tutti i piani si applicano dei limiti di frequenza; consulta la documentazione dell'API per i limiti attuali per app.

Quali linguaggi di programmazione supporta Quire API?

L'API si basa su HTTP, con corpi di richiesta e risposta in JSON: funziona quindi qualsiasi linguaggio con un client HTTP e un parser JSON. Gli esempi di questo articolo sono in JavaScript, ma lo stesso flusso funziona in modo identico in Python, Go, Ruby, PHP e qualsiasi altro linguaggio.

Non esiste una libreria client ufficiale; la superficie dell'API è abbastanza piccola da rendere comune l'uso di un sottile wrapper attorno al client HTTP del tuo linguaggio.

Quanto durano gli access token di Quire?

Per impostazione predefinita, gli access token scadono dopo un'ora. I refresh token durano di più e permettono di ottenere nuovi access token senza chiedere di nuovo l'autorizzazione all'utente. Integra il ciclo del refresh token nella tua app fin dal primo giorno.

Posso usare Quire API per l'accesso in sola lettura?

Sì. Gli scope OAuth ti permettono di richiedere solo i permessi di cui la tua app ha bisogno. Se la tua app legge soltanto le attività, richiedi scope di lettura. Gli utenti di Quire vedranno gli scope richiesti nella pagina di autorizzazione e potranno rifiutare se la richiesta sembra eccessiva: chiedere troppo riduce le conversioni.

Qual è la differenza tra Quire API e il server Quire MCP?

L'API è una superficie REST generica per qualsiasi app che voglia leggere o modificare i dati di Quire per conto di un utente. Il server MCP è pensato apposta per Claude e altri agenti LLM: gestisce l'autenticazione, espone uno schema di strumenti standard e ti evita di scrivere codice OAuth. Usa l'API per le integrazioni tradizionali; usa MCP per le integrazioni con agenti LLM.

E ora, da dove si riparte?

Ecco il flusso OAuth 2.0 completo per Quire API: configurazione dell'app OAuth, autorizzazione in quattro passaggi, uso dell'access token e ciclo di refresh. Il motivo più comune per cui gli sviluppatori rilasciano un'integrazione funzionante che si rompe due giorni dopo è trattare il ciclo di refresh come una correzione da fare più avanti, invece di integrarlo fin dal primo giorno.

Inizia dalla console per sviluppatori di Quire o leggi il riferimento API completo. Se preferisci non scrivere affatto codice OAuth, il server Quire MCP gestisce l'autenticazione per te ed è la scelta giusta per le integrazioni con agenti LLM.

Per le integrazioni basate sugli eventi, i Webhooks sono di solito più adatti del polling in cui finiscono la maggior parte delle prime integrazioni API. E se vuoi solo eseguire rapide modifiche da script senza creare un'app OAuth, la CLI di Quire esegue i comandi di gestione dei progetti direttamente dal terminale.