Autenticazione

Guida completa all'autenticazione delle API Queria.

Metodi di Autenticazione

1. JWT Token (Utenti)

Per utenti che accedono via dashboard o applicazioni custom.

Authorization: Bearer <jwt-token>

2. API Key (Integrazioni)

Per widget e integrazioni server-to-server.

X-API-Key: qk_live_xxxxxxxxxxxxxxxx

JWT Authentication

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user-uuid",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "COMPANY_ADMIN"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600
  }
}

Token Refresh

I token JWT scadono dopo 1 ora. Usa il refresh token per ottenere nuovi token:

POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

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

Logout

POST /api/auth/logout
Authorization: Bearer <token>

Token Structure

Il JWT contiene:

{
  "sub": "user-uuid",
  "email": "user@example.com",
  "role": "COMPANY_ADMIN",
  "companyId": "company-uuid",
  "iat": 1704067200,
  "exp": 1704070800
}

API Key Authentication

Generare API Key

1. Accedi alla dashboard
2. Vai su Impostazioni > API Keys
3. Click Genera Nuova Key
4. Copia subito la key (mostrata una sola volta)

Formato API Key

qk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
qk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• qk_live_: Chiave produzione
• qk_test_: Chiave test (se disponibile)

Utilizzo

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

Domini Autorizzati

Per sicurezza, configura i domini da cui l'API key può essere usata:

# Dashboard > Impostazioni > API Keys > Modifica

Domini autorizzati:
- example.com
- *.example.com
- app.mysite.it

Le richieste da domini non autorizzati riceveranno errore 403.

Rotazione Key

Per ruotare una API key:

1. Genera una nuova key
2. Aggiorna le integrazioni
3. Elimina la vecchia key

Attenzione

L'eliminazione di una key è immediata. Assicurati che nessuna integrazione la stia usando.

Ruoli e Permessi (RBAC)

Ruoli Disponibili

Ruolo	Descrizione
SYSTEM_ADMIN	Accesso completo piattaforma
COMPANY_ADMIN	Gestione completa azienda
COMPANY_EDITOR	CRUD documenti e chat
COMPANY_READER	Solo lettura

Matrice Permessi

Azione	SYSTEM_ADMIN	COMPANY_ADMIN	COMPANY_EDITOR	COMPANY_READER
Gestione aziende	✅	❌	❌	❌
Configurazione RAG	✅	✅	❌	❌
Gestione utenti	✅	✅	❌	❌
Upload documenti	✅	✅	✅	❌
Elimina documenti	✅	✅	✅	❌
Chat AI	✅	✅	✅	✅
Visualizza documenti	✅	✅	✅	✅

Verifica Ruolo

GET /api/auth/me
Authorization: Bearer <token>

# Response
{
  "success": true,
  "data": {
    "id": "user-uuid",
    "email": "user@example.com",
    "role": "COMPANY_ADMIN",
    "company": {
      "id": "company-uuid",
      "name": "ACME Corp"
    }
  }
}

Errori Autenticazione

401 Unauthorized

Token mancante o invalido:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

Soluzioni:

• Verifica che il token sia presente nell'header
• Controlla che il token non sia scaduto
• Ottieni un nuovo token con refresh

403 Forbidden

Permessi insufficienti:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this resource"
  }
}

Soluzioni:

• Verifica il ruolo dell'utente
• Contatta l'admin per permessi aggiuntivi

API Key Errors

Dominio non autorizzato:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Domain not allowed for this API key"
  }
}

Key non valida:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Best Practices

Token Management

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

API Keys

• Non committare API keys nel codice
• Usa variabili ambiente
• Ruota le keys periodicamente
• Limita i domini autorizzati

Sicurezza

• Usa sempre HTTPS
• Implementa rate limiting lato client
• Monitora l'uso delle API keys
• Invalida immediatamente keys compromesse