Autenticazione

Tutte le richieste alle API di Felo API Platform richiedono l'autenticazione tramite una chiave API. Questa guida spiega come autenticare le richieste e gestire i problemi di autenticazione più comuni.

Autenticazione con chiave API

Felo usa l'autenticazione con chiave API per tutti gli endpoint v2. La tua chiave API identifica la tua applicazione e dà accesso alle capacità della piattaforma.

Come funziona

1. Ottieni una chiave API dalla pagina Chiavi API di Felo API Platform
2. Includi la chiave API nell'header Authorization di ogni richiesta API
3. La piattaforma convalida la tua chiave API ed elabora la richiesta

Formato dell'header

Includi la chiave API nell'header Authorization usando lo schema di autenticazione Bearer:

Authorization: Bearer YOUR_API_KEY

Richiesta di esempio

curl -X POST https://openapi.felo.ai/v2/chat \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is machine learning?"}'

Ottenere la chiave API

Per ottenere la chiave API:

1. Apri la pagina Chiavi API di Felo API Platform
2. Accedi con il tuo account Felo se richiesto
3. Inserisci un nome per la chiave e clicca Create Key
4. Copia la chiave completa quando viene mostrata. Viene visualizzata una sola volta
5. Conserva la chiave in un luogo sicuro e usala come FELO_API_KEY

Buone pratiche di sicurezza

1. Conserva le chiavi API in modo sicuro

Non inserire le chiavi API direttamente nel codice sorgente:

# ❌ Bad - API Key exposed in code
api_key = "sk_live_abc123xyz789"

Sì, usa variabili d'ambiente o una configurazione sicura:

# ✅ Good - API Key from environment
import os
api_key = os.environ.get('FELO_API_KEY')

2. Usa le variabili d'ambiente

Conserva la chiave API nelle variabili d'ambiente:

Linux/macOS:

export FELO_API_KEY="sk_live_abc123xyz789"

Windows (Prompt dei comandi):

set FELO_API_KEY=sk_live_abc123xyz789

Windows (PowerShell):

$env:FELO_API_KEY="sk_live_abc123xyz789"

3. Ruota le chiavi regolarmente

Genera periodicamente nuove chiavi API e revoca quelle vecchie per ridurre al minimo i rischi di sicurezza.

4. Usa chiavi diverse per ambienti diversi

Crea chiavi API separate per gli ambienti di sviluppo, staging e produzione.

5. Non esporre mai le chiavi nel codice lato client

Le chiavi API vanno usate solo nel codice lato server. Non includerle mai in:

• Codice JavaScript frontend
• Codice sorgente di app mobile
• Repository pubblici
• File di configurazione lato client

Errori di autenticazione

Per la struttura completa degli errori, gli header di rate limit e la politica di retry, vedi Errori, limiti e retry.

Codici di errore comuni

Una richiesta rifiutata restituisce lo stato della chiave in message:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key is required",
  "request_id": "..."
}

status è il codice di stato HTTP. Una chiave revocata riporta API Key has been revoked (keyPrefix=...). Basa la logica sullo stato HTTP e su code, non sul testo esatto di message.

Risoluzione dei problemi

Se l'autenticazione non funziona:

1. Controlla che l'header sia esattamente Authorization: Bearer YOUR_API_KEY.
2. Verifica che la chiave non sia stata revocata nella pagina Chiavi API.
3. Verifica che l'ambiente stia usando la chiave che ti aspetti.
4. Genera una nuova chiave se quella vecchia è stata eliminata o ruotata. Una chiave completa viene mostrata una sola volta, al momento della creazione.

Per una checklist basata sui sintomi che copre l'autenticazione e il resto della piattaforma, vedi Risoluzione dei problemi.

Esempio: eseguire il debug dell'autenticazione

import requests

url = "https://openapi.felo.ai/v2/chat"
api_key = "YOUR_API_KEY"

# Correct format
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={"query": "test"})

if response.status_code == 401:
    error = response.json()
    print(f"Authentication failed: {error['code']}")
    print(f"Message: {error['message']}")
    print(f"Request ID: {error['request_id']}")
else:
    print("Authentication successful!")

Rate limiting

I rate limit sono applicati per endpoint, non globalmente per chiave API. Attualmente solo `/v2/chat` li applica; gli utenti con un abbonamento Felo a pagamento attivo ne sono esenti. Gli altri endpoint /v2/** non hanno rate limit applicati.

Una risposta 429 include gli header X-RateLimit-* e Retry-After. Leggi sempre i limiti effettivi dagli header della risposta, non dalla documentazione.

Per le dimensioni complete dei rate limit, gli header e la politica di retry, vedi Errori, limiti e retry.

Serve aiuto?

Se riscontri problemi di autenticazione:

1. Rileggi con attenzione questa guida
2. Consulta la guida Per iniziare
3. Verifica la tua chiave API nella pagina Chiavi API
4. Contatta il supporto all'indirizzo [email protected] indicando il tuo request ID

Passi successivi

• Guida per iniziare - Scopri come effettuare la prima chiamata API
• Riferimento Chat API - Esplora la documentazione della Chat API