Autenticazione API e token Bearer

Come funziona l'autenticazione

1. Registrati e accedi al tuo account Quote3D.
2. Genera un token API (JWT) dalla tua dashboard nella scheda "Tokens".
3. Includi il token nelle tue richieste API. Sono supportati Authorization: Bearer e X-API-Token:
   Authorization: Bearer YOUR_TOKEN_HERE
4. Il server verifica il tuo token e concede l'accesso se è valido e non scaduto.

Ambiti dei token

L'ambito di un token stabilisce quali endpoint può raggiungere. Lo scegli quando crei il token e puoi vederlo nella pagina Token del pannello.

• Accesso completo — l'impostazione predefinita per un token lato server. Raggiunge ogni endpoint consentito dal tuo piano.
• Widget — l'ambito da usare per un token incorporato in un negozio. È limitato a ciò che serve al widget integrabile e non può raggiungere webhook, dati dell'account, analisi, utilizzo o quote.

Una chiamata a un endpoint fuori dall'ambito del token viene respinta con 403 anche se il token è valido. Se una richiesta fallisce con 403 mentre lo stesso token funziona altrove, controlla prima di tutto il suo ambito.

Ciclo di vita dei token

• Il valore di un token viene mostrato una sola volta, alla creazione. Non è recuperabile in seguito — salvalo subito nel tuo gestore di segreti. Se lo perdi, ruota il token per ottenere un nuovo valore.
• I token possono essere creati con una scadenza. Un token scaduto smette di funzionare e restituisce 401; il pannello mostra la data di scadenza di ciascun token.
• Ruotare un token emette un nuovo valore e invalida subito quello vecchio. Distribuisci il nuovo valore prima di ruotare, perché le richieste in corso con il vecchio token iniziano a fallire immediatamente.
• Un token può essere limitato a un elenco di indirizzi IP. Le chiamate da qualsiasi altro indirizzo vengono respinte con 403 — una sorpresa frequente dopo lo spostamento di un server o il cambio di un gateway NAT.
• Il tuo piano limita quanti token puoi avere. I piani gratuiti consentono un token server e un token widget.

Quando l'autenticazione fallisce

Una richiesta respinta restituisce l'involucro di errore standard con success: false e un breve messaggio. Basa la logica sul codice di stato HTTP e non sul testo del messaggio, che può essere riformulato.

{
  "success": false,
  "error": "API token has expired"
}

• 401 — il token è mancante, malformato, scaduto o revocato. Controlla il nome dell'header e che il valore non sia stato troncato durante la copia.
• 403 — il token è valido ma non consentito per questa chiamata. Le cause abituali sono una restrizione di ambito o un elenco IP che non include il chiamante.

Formato del token

I token Quote3D sono credenziali API di tipo bearer. I client dovrebbero trattarli come segreti opachi ed evitare di dipendere dalla struttura interna del token.

Un JWT è composto da tre parti:

1. Header: Specifica l'algoritmo di firma e il tipo di token.
2. Payload: Contiene i dati dell'utente e le affermazioni (come ID utente, email e tempo di scadenza).
3. Signature: Verifica che il token non sia stato manomesso.

Un JWT ha questo aspetto:

Per le integrazioni, la regola importante è semplice: memorizza il token in modo sicuro, invialo con ogni richiesta ed evita di analizzarlo o esporlo nel codice client a meno che l'integrazione non richieda esplicitamente un token lato client.

Esempio: Utilizzo del Tuo Token

Ecco come puoi utilizzare il tuo token con curl. Utilizza uno stile di header di autenticazione in modo coerente:

Oppure, nell'API playground, incolla il tuo token nella finestra modale di autorizzazione (icona a lucchetto) per autenticare la tua sessione. Puoi anche utilizzare X-API-Token in integrazioni personalizzate se tale header si adatta meglio.