Diventa un Eroe: Crea la Tua App con Quire API

Ultimo aggiornamento: 28 maggio 2026

TL;DR: La Quire API OAuth 2.0 permette alla tua app di agire sull'account Quire di un utente senza memorizzare la sua password. Avrai bisogno di un'app OAuth registrata (client ID, secret, URL di redirezione), di un flusso di autorizzazione in quattro passaggi (configura, reindirizza, gestisci la risposta, scambia il codice per il token) e di un ciclo di aggiornamento del token, poiché i token di accesso scadono dopo un'ora.

Costruire un'app che legge o modifica i dati Quire di un utente parte da una decisione: come autenticarsi senza mai vedere la password dell'utente? La Quire API risponde a questa domanda con OAuth 2.0. Questo articolo illustra la configurazione dell'app OAuth, il flusso di autorizzazione in quattro passaggi, il ciclo di accesso e aggiornamento del token, e gli errori più comuni che i developer commettono alla prima build.

La versione 1.0.0 dell'OpenAPI di Quire è stata rilasciata nell'ottobre 2019 ed è rimasta stabile. Con OAuth, gli utenti autorizzano la tua app ad accedere ai loro contenuti Quire (attività, progetti, commenti, assegnazioni, etichette, data di scadenza) senza che tu tocchi mai le loro credenziali. L'utente può revocare quell'accesso in qualsiasi momento senza cambiare la password — motivo per cui le integrazioni che memorizzano le password erano un antipattern di sicurezza prima che OAuth le rendesse inutili.

Quale approccio di integrazione Quire è adatto al tuo caso d'uso?

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

Se stai costruendo una tipica integrazione applicativa (app mobile, dashboard web, servizio di sincronizzazione), l'API OAuth è ciò di cui hai bisogno. Il resto di questo articolo assume che tu stia seguendo questa strada.

Come si configura un'app OAuth per la Quire API?

Per utilizzare la Quire API, dovrai creare un'app OAuth.

Crea la tua app OAuth Quire

Dovrai essere connesso al tuo account Quire per creare un'app.

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 potranno visualizzare e modificare tutte le Apps appartenenti all'organizzazione selezionata.

3. Assegna un nome alla tua applicazione e inserisci un URL di redirezione; discuteremo il ruolo dell'URL di redirezione 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 apparirà nella pagina della console per sviluppatori, dove potrai configurarla ulteriormente.

In sintesi, dovresti avere questi tre elementi:

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

Come si configura l'ambiente di sviluppo per la Quire API?

Passaggio 1. Configura la tua app

Inserisci le informazioni di configurazione della tua applicazione nell'app.

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 gli utenti all'endpoint OAuth di Quire. Questo mostrerà una pagina web in cui gli utenti Quire connessi potranno 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

Un esempio di link di autorizzazione potrebbe apparire così:

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 attacchi Cross-Site Request Forgery (CSRF). Dovresti generare una stringa di caratteri in modo casuale. Verrà restituita alla tua app, invariata, nel Passaggio 3. La tua applicazione dovrebbe validare questo valore. Sebbene sia opzionale, consigliamo vivamente di includere questo parametro.

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 utilizzando l'URL specificato nel redirect_uri.

Se l'utente approva la richiesta di accesso, la risposta contiene un codice di autorizzazione. Se l'utente non approva la richiesta, la risposta contiene un messaggio di errore. Il codice di autorizzazione o il messaggio di errore restituito al server web appare nella stringa di query, 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 apparire così:

//...
} 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 alla redirect_uri della tua applicazione, nella stringa di query saranno presenti anche un parametro code e un parametro state. Il parametro state è il tuo token anti-forgery CSRF per validare la richiesta.

Estrai code e state dai parametri della stringa di query. A questo punto è possibile validare lo state.

Un esempio di validazione potrebbe apparire così:

} 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 per il token di accesso

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

Un esempio di richiesta di un token di accesso potrebbe apparire così:

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

Il token di accesso 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 deve essere conservato con cura e in modo permanente, poiché è necessario per accedere a ogni endpoint della Quire API.

Come si effettuano chiamate API con il token di accesso Quire?

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

Chiama l'API

Effettua la chiamata API passando il token di accesso come bearer token nell'intestazione della richiesta.

Un esempio di chiamata API potrebbe apparire così:

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 token di accesso Quire API scaduto?

Un token di accesso è intenzionalmente pensato per un uso a breve termine. Questo è un meccanismo di sicurezza fondamentale di OAuth 2.0. Usando l'Authorization Code Grant Flow, i token di accesso hanno una durata predefinita di un'ora.

Quando un token di accesso scade, viene restituito un errore HTTP 401:

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

La tua applicazione avrà bisogno di aggiornare il token di accesso.
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 potrebbe reindirizzare l'utente al flusso di autenticazione.

Quali sono gli errori più comuni che i developer commettono con la Quire API?

Dopo aver osservato numerosi team costruire integrazioni con la Quire API, gli stessi cinque problemi si ripresentano sempre. Nessuno è sottile; tutti sono evitabili.

1. Memorizzare il client secret nel codice lato client. Il client secret è esattamente quello che dice: un segreto. Se finisce nel binario di un'app mobile o in un bundle per il browser, chiunque può estrarlo e impersonare la tua app. Il secret deve risiedere solo su un server che controlli. Se la tua app è puramente lato client (single-page app, mobile), usa il flusso OAuth 2.0 PKCE invece di incorporare il secret.

2. Dimenticare di validare il parametro state. Il parametro state esiste per prevenire gli attacchi CSRF. Se salti la sua validazione nel callback, hai lasciato una vulnerabilità che un sito malevolo può sfruttare per associare silenziosamente un account Quire alla sessione dell'app di un attaccante. Genera state per ogni richiesta, salvalo nella sessione e rifiuta qualsiasi callback in cui lo state restituito non corrisponde.

3. Trattare il token di accesso come permanente. I token di accesso scadono dopo un'ora. Le Apps che memorizzano il token senza mai aggiornarlo funzionano bene il primo giorno e si rompono silenziosamente il secondo. Costruisci il ciclo del refresh token prima di rilasciare qualsiasi cosa, non come una correzione da fare "quando gli utenti si lamentano".

4. Fare polling dell'API per rilevare i cambiamenti. Il polling consuma rate limit, introduce latenza e scarica la batteria. Se hai bisogno di reagire ai cambiamenti in Quire, usa i Webhooks. Il webhook ti invia l'evento istantaneamente; la chiamata API che avresti fatto per rilevare quell'evento non deve mai avvenire.

5. Saltare la lista di URL di redirezione consentiti. Ogni registrazione di app OAuth accetta un elenco di URL di redirezione. Se usi un wildcard o non lo configuri con precisione, un attaccante può registrare il proprio callback come target di reindirizzamento e intercettare i codici di autorizzazione. Aggiungi solo gli URL esatti che la tua app effettivamente utilizza.

Se stai sviluppando contro l'API per la prima volta, il modo più rapido per apprendere i pattern è fare un fork di un'integrazione esistente come il connettore n8n e studiare come gestisce autenticazione, aggiornamento del token e stati di errore.

Quando la Quire API non è la scelta giusta?

Tre scenari in cui è meglio usare una superficie di integrazione diversa.

• Hai solo bisogno di reagire agli eventi, non di interrogare lo stato. I Webhooks sono più semplici, push-based, e non richiedono l'autorizzazione utente per le sottoscrizioni a eventi in sola lettura. Se il compito della tua app è "avvisami quando succede qualcosa", usa i Webhooks, non l'API.
• Stai costruendo un'integrazione con Claude o un agente LLM. Il server Quire MCP è la superficie giusta in questo caso. Gestisce l'autenticazione, fornisce uno schema standard e ti evita di scrivere codice OAuth da zero. MCP è progettato appositamente per questo; implementare la stessa cosa con l'API OAuth richiede più lavoro per lo stesso risultato.
• Hai bisogno di un'esportazione dati una tantum. Se devi estrarre i dati di un progetto una sola volta per analisi o backup, l'integrazione n8n o un'esportazione CSV manuale ti faranno risparmiare una settimana di sviluppo.

Se nessuno di questi casi si applica, l'API OAuth è lo strumento che fa per te.

Domande frequenti

La Quire API richiede un piano Quire a pagamento?

No. La Quire API è disponibile su ogni piano, incluso il Free tier. I limiti di frequenza si applicano a tutti i piani; consulta la documentazione API per i limiti attuali per app.

Quali linguaggi di programmazione supporta la Quire API?

L'API è basata su HTTP con corpo delle richieste e risposte in JSON, quindi qualsiasi linguaggio con un client HTTP e un parser JSON funziona. Gli esempi in 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 il pattern comune un sottile wrapper attorno al client HTTP del proprio linguaggio.

Quanto durano i token di accesso di Quire?

I token di accesso scadono dopo un'ora per impostazione predefinita. I refresh token durano più a lungo e possono essere usati per ottenere nuovi token di accesso senza richiedere nuovamente il consenso all'utente. Integra il ciclo del refresh token nella tua app fin dal primo giorno.

Posso usare la Quire API per un 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 solo le attività, richiedi scope di sola lettura. Gli utenti Quire vedranno gli scope richiesti nella pagina di autorizzazione e possono rifiutare se la richiesta sembra eccessiva, quindi richiedere troppo penalizza la conversione.

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

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

Dove andare da qui?

Questo è il flusso OAuth 2.0 completo per la Quire API: configurazione dell'app OAuth, autorizzazione in quattro passaggi, utilizzo del token di accesso e ciclo di aggiornamento. La ragione più comune per cui i developer rilasciano un'integrazione funzionante che si rompe due giorni dopo è trattare il ciclo di aggiornamento come una correzione futura invece di integrarlo fin dall'inizio.

Inizia dalla console per sviluppatori di Quire o leggi il riferimento API completo. Se preferisci non scrivere codice OAuth, il server Quire MCP gestisce l'autenticazione per te ed è la scelta giusta per le integrazioni con agenti LLM. Per le integrazioni event-driven, i Webhooks sono generalmente più adatti del pattern di polling con cui finiscono la maggior parte delle integrazioni API alla prima esperienza.