Sii un eroe: crea la tua App con Quire API

Ultimo aggiornamento: 28 maggio 2026

TL;DR: L'API OAuth 2.0 di Quire consente alla tua app di agire sull'account Quire di un utente senza memorizzarne la password. Avrai bisogno di un'app OAuth registrata (client ID, secret, URL di redirezione), di un flusso di autorizzazione in quattro passaggi (configurazione, reindirizzamento, gestione della risposta, scambio del codice per il token) e di un ciclo del token di aggiornamento, poiché i token di accesso scadono dopo un'ora.

Sviluppare un'app che legga o modifichi i dati Quire di un utente inizia con una decisione: come autenticarsi senza mai vedere la password dell'utente? La Quire API risponde 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 i modi più comuni in cui gli sviluppatori sbagliano 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 Ora senza cambiare la password — ecco perché le integrazioni che memorizzavano le password erano un antipattern di sicurezza prima che OAuth le rendesse superflue.

Quale approccio di integrazione Quire si adatta al tuo caso d'uso?

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

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

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

Per creare un'app dovrai essere connesso 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 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 fornire il seguente URL:

   http://localhost:3000/callback

4. Clicca sul pulsante Crea nuova app: la tua nuova applicazione OAuth verrà presentata 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
• 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 dell'applicazione nella tua 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 i tuoi utenti all'endpoint OAuth di Quire. Verrà mostrata 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 utilizzata per prevenire gli 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 facoltativo, ti 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 in 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 al redirect_uri della tua applicazione, nella stringa di query saranno presenti anche i parametri code e state. Il parametro state è il tuo token anti-CSRF da validare.

Estrai il codice e lo stato dai parametri della stringa di query. A questo punto lo stato può essere validato.

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 con 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 di richiesta indicati di seguito.

Un esempio di richiesta di 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.

Risposta di esempio:

{ 
  "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 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 utilizzato 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))
          });
    });
}

Risposta di esempio:

{
  "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 progettato per un utilizzo a breve termine. Questo è un importante meccanismo di sicurezza di OAuth 2.0. Quando si utilizza il flusso Authorization Code Grant, i token di accesso hanno una durata predefinita di un'ora.

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

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

Your application will need to refresh the 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 potrebbe reindirizzare l'utente al flusso di autenticazione.

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

Dopo aver osservato team che sviluppano con la Quire API, gli stessi cinque problemi si ripresentano regolarmente. Nessuno è sottile; tutti sono evitabili.

1. Inserire il client secret nel codice lato client. Il client secret è esattamente 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 vivere solo su un server sotto il tuo controllo. Se la tua app è puramente lato client (single-page app, mobile), usa il flusso OAuth 2.0 PKCE invece di incorporare il secret.

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

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 perfettamente il primo giorno e si rompono silenziosamente il secondo. Costruisci il ciclo del token di aggiornamento prima di rilasciare qualsiasi cosa, non come una "correzione quando gli utenti si lamentano".

4. Eseguire polling dell'API per rilevare i cambiamenti. Il polling consuma il limite di frequenza, aumenta la latenza e scarica la batteria. Se hai bisogno di reagire ai cambiamenti in Quire, usa invece i Webhooks. Il webhook ti recapita l'evento istantaneamente; la chiamata API che avresti dovuto fare per rilevare quell'evento non deve mai avvenire.

5. Saltare la lista di URL di redirezione autorizzati. Ogni registrazione di app OAuth accetta un elenco di URL di redirezione. Se usi caratteri jolly o salti una configurazione precisa, un attaccante può registrare il proprio callback come destinazione del tuo URL di redirezione e intercettare i codici di autorizzazione. Aggiungi solo gli URL esatti che la tua app utilizza effettivamente.

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

Quando la Quire API non è la scelta giusta?

Tre scenari in cui dovresti optare per una superficie di integrazione diversa.

• Devi solo reagire agli eventi, non interrogare lo stato. I Webhooks sono più semplici, push-based, e non richiedono autorizzazione utente per gli Abbonamenti a eventi di sola lettura. Se il compito della tua app è "avvisami quando succede qualcosa", usa i Webhooks, non l'API.
• Stai sviluppando un'integrazione con Claude o un agente LLM. Il server MCP di Quire è la superficie giusta in questo caso. Gestisce l'autenticazione, espone uno schema di strumenti standard e fa sì che tu non debba scrivere codice OAuth da zero. MCP è progettato appositamente per questo; farlo da soli con l'API OAuth richiede più lavoro per lo stesso risultato.
• Stai eseguendo un'esportazione dati una tantum. Se hai solo bisogno di estrarre i dati di un progetto una volta per analisi o backup, l'Integrazione n8n o un'esportazione CSV manuale ti faranno risparmiare una settimana di sviluppo.

Se nessuno di questi scenari si applica, l'API OAuth è il tuo strumento.

Domande frequenti

La Quire API richiede un piano Quire a pagamento?

No. La Quire API è disponibile su tutti i piani, incluso il livello gratuito. 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 corpi di richiesta e risposta in JSON, quindi funziona qualsiasi linguaggio dotato di un client HTTP e di un parser JSON. 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 ridotta da rendere il pattern comune un sottile wrapper attorno al client HTTP del tuo linguaggio.

Quanto durano i token di accesso di Quire?

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

Posso usare la Quire API solo per l'accesso in lettura?

Sì. Gli scope OAuth ti permettono di richiedere solo i Permessi necessari alla tua app. Se la tua app legge solo le Attività, richiedi scope di sola lettura. Gli utenti Quire vedranno gli scope richiesti sulla 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 MCP di Quire?

L'API è una superficie REST per uso generale, adatta a qualsiasi app che voglia leggere o modificare 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 fa sì che tu non debba 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. Il motivo più comune per cui gli sviluppatori rilasciano un'integrazione funzionante che si rompe due giorni dopo è trattare il ciclo di aggiornamento come una correzione da fare in seguito invece di integrarlo fin dal primo giorno.

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