Autenticazione

Queria supporta diversi metodi di autenticazione per coprire ogni scenario di integrazione, dalle applicazioni web interattive alle integrazioni server-to-server.

Metodi di Autenticazione

Metodo	Uso principale	Header
JWT Token	Sessioni utente (dashboard, app web)	Authorization: Bearer {token}
API Key	Integrazioni e widget	X-API-Key: {key}

JWT (JSON Web Token)

Il metodo JWT e indicato per le applicazioni web con sessioni utente.

Login

curl -X POST https://api.queria.pro/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "utente@azienda.it",
    "password": "password_sicura"
  }'

Risposta:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "rt_9f8e7d6c5b4a3210...",
    "expiresIn": 3600,
    "user": {
      "id": "usr_a1b2c3",
      "email": "utente@azienda.it",
      "name": "Mario Rossi",
      "role": "COMPANY_ADMIN",
      "companyId": "comp_x1y2z3"
    }
  }
}

L'access token ha una validita di 1 ora. Includilo in ogni richiesta:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Struttura del Token

Il JWT contiene le seguenti informazioni:

{
  "sub": "usr_a1b2c3",
  "email": "utente@azienda.it",
  "role": "COMPANY_ADMIN",
  "companyId": "comp_x1y2z3",
  "iat": 1709542800,
  "exp": 1709546400
}

Refresh del Token

Prima della scadenza, rinnova il token con il refresh token:

curl -X POST https://api.queria.pro/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "rt_9f8e7d6c5b4a3210..."
  }'

Risposta:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "rt_a1b2c3d4e5f60000...",
    "expiresIn": 3600
  }
}

Logout

curl -X POST https://api.queria.pro/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Verifica Sessione

curl -X GET https://api.queria.pro/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key

Le API Key sono il metodo consigliato per integrazioni server-to-server e widget.

Formato

Ambiente	Prefisso	Esempio
Produzione	qk_live_	qk_live_abc123def456ghi789jkl012
Test	qk_test_	qk_test_mno345pqr678stu901vwx234

Utilizzo

Includi la chiave nell'header X-API-Key:

curl -X POST https://api.queria.pro/api/public/chat \
  -H "X-API-Key: qk_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{"message": "Qual e la policy sulle ferie?"}'

Generazione

Le API Key si generano dalla dashboard di amministrazione:

1. Accedi a Impostazioni nel pannello admin
2. Seleziona API Keys
3. Clicca su Genera Nuova Key
4. Copia immediatamente la chiave (viene mostrata una sola volta)
5. Configura le restrizioni (opzionale)

Domini Autorizzati

Per sicurezza, configura i domini da cui l'API Key puo essere utilizzata:

# Dashboard > Impostazioni > API Keys > Modifica

Domini autorizzati:
- esempio.com
- *.esempio.com
- app.miosito.it

Le richieste da domini non autorizzati riceveranno errore 403.

Attenzione

L'eliminazione di una key e immediata e irreversibile. Assicurati che nessuna integrazione la stia utilizzando prima di procedere.

OAuth (Social Login)

Queria supporta l'autenticazione tramite provider OAuth.

Google

curl -X POST https://api.queria.pro/api/auth/google \
  -H "Content-Type: application/json" \
  -d '{"idToken": "google_id_token_here"}'

Microsoft

curl -X POST https://api.queria.pro/api/auth/microsoft \
  -H "Content-Type: application/json" \
  -d '{"accessToken": "microsoft_access_token_here"}'

Entrambi restituiscono lo stesso formato di risposta del login standard con accessToken e refreshToken.

Ruoli e Permessi (RBAC)

Il sistema utilizza un modello RBAC gerarchico per il controllo degli accessi.

Ruolo	Ambito	Descrizione
COMPANY_ADMIN	Azienda	Gestione utenti, documenti, impostazioni aziendali
COMPANY_EDITOR	Azienda	Upload, modifica e cancellazione documenti, utilizzo chat
COMPANY_READER	Azienda	Sola lettura documenti e utilizzo chat

Matrice Permessi

Azione	COMPANY_ADMIN	COMPANY_EDITOR	COMPANY_READER
Configurazione Cog-RAG	Si	No	No
Gestione utenti	Si	No	No
Upload documenti	Si	Si	No
Elimina documenti	Si	Si	No
Chat AI	Si	Si	Si
Visualizza documenti	Si	Si	Si

Errori di Autorizzazione

401 Unauthorized - Token mancante o scaduto:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token mancante o non valido"
  }
}

403 Forbidden - Permessi insufficienti:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Permessi insufficienti. Ruolo richiesto: COMPANY_ADMIN.",
    "requiredRole": "COMPANY_ADMIN",
    "currentRole": "COMPANY_READER"
  }
}

403 Forbidden - Dominio non autorizzato (API Key):

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Dominio non autorizzato per questa API Key"
  }
}

Best Practice di Sicurezza

Gestione dei Token

• Non salvare i token in localStorage (vulnerabile a XSS)
• Utilizza httpOnly cookies quando possibile
• Implementa il refresh automatico prima della scadenza del token

API Key

• Non includere API Key nel codice client-side
• Utilizza variabili d'ambiente per conservare le chiavi nei server
• Ruota le chiavi regolarmente (almeno ogni 90 giorni)
• Limita i domini autorizzati per ogni chiave

Scelta del Metodo

Scenario	Metodo consigliato
Applicazione web con login utente	JWT
Widget incorporato in siti terzi	API Key con restrizione dominio
Integrazione server-to-server	API Key
Applicazione mobile	JWT con refresh token
Script di automazione	API Key con scadenza

Regole Fondamentali

• Utilizza sempre HTTPS per tutte le comunicazioni
• Implementa rate limiting lato client per evitare blocchi
• Monitora l'utilizzo delle chiavi dalla dashboard
• Revoca immediatamente le chiavi compromesse