ADR 0004 — Autenticazione Odoo 18 con API Key richiede username¶
Status: accepted
Date: 2026-04-26
Context¶
Odoo 18 supporta l'autenticazione tramite API Key, ma usa il percorso
legacy (/web/session/authenticate), non il Bearer token introdotto
in Odoo 19. In questo percorso, l'API key viene passata come valore del
campo password, mentre il campo user deve contenere un vero login utente.
Il codice precedente consentiva di configurare un'istanza v18 con solo
api_key_env (senza username). Il metodo _build_auth_kwargs in
client.py avrebbe quindi passato user=None a odooly.Client,
causando un fallimento silenzioso dell'autenticazione.
Odoo 19 usa invece user="__api_key__" come sentinella, rendendo il
username non necessario.
Decision¶
Per Odoo 18, il campo username è obbligatorio quando si usa
api_key_env. La validazione viene applicata in
config._validate_auth_fields con un ValueError esplicito:
"username is required for Odoo 18 when using api_key_env
(v18 uses the legacy auth path: api_key as password, real username required)"
Il comportamento per versione è quindi:
| Versione | Auth method | username |
api_key_env |
password_env |
|---|---|---|---|---|
| 16 / 17 | password | richiesto | vietato | richiesto |
| 18 | api_key (legacy) | richiesto | opzionale | opzionale |
| 18 | password | richiesto | — | richiesto |
| 19 | api_key (Bearer) | facoltativo | richiesto | — |
| 19 | password | richiesto | — | richiesto |
Consequences¶
Positivo:
- Il fallimento di autenticazione è catturato al momento del caricamento
della configurazione (ConfigError), non al momento della connessione.
- Il comportamento di v18 è coerente e documentato.
Negativo:
- Chi aveva configurato v18 con solo api_key_env (senza username)
riceverà un ConfigError alla prossima esecuzione: dovrà aggiungere
username a instances.json.