WooCommerce dice che la chiave è sbagliata, e la chiave è giusta

Generi la chiave, la incolli, errore. La rigeneri, errore. Fra le cause elencate dalla documentazione ufficiale ce ne sono tre che non hanno niente a che fare con la chiave — e danno tre risposte diverse.

Generi la chiave dal pannello di WooCommerce. Copi la chiave, copi il segreto, li incolli nel software. Errore. Rifai tutto un carattere alla volta, controllando che non restino spazi in fondo. Stesso errore.

E la chiave è giusta. La documentazione ufficiale di WooCommerce prevede esattamente questo caso, e lo attribuisce al server, non a te. Sono parole loro: «Occasionally some servers may not parse the Authorization header correctly (if you see a “Consumer key is missing” error when authenticating over SSL, you have a server issue)».

Ma i tre guasti non hanno lo stesso sintomo

Gira il riassunto comodo: «è sempre la stessa cosa, tanto l'errore che vedi è identico». Non regge, e per fortuna. Fra le cause elencate dalla documentazione ufficiale ce ne sono tre che danno risposte diverse, e quella differenza è tutta la diagnosi.

• Un errore che parla della chiave, mentre sei su HTTPS → guarda il server, non la chiave.
• Un 404 su /wp-json/ → guarda i permalink: quell'indirizzo non è una rotta.
• Sei su http:// senza S → chiave e segreto non vengono letti come credenziali Basic.

Ramo 1 — l'intestazione che sparisce per strada

Su HTTPS l'autenticazione è semplicissima: «You may use HTTP Basic Auth by providing the REST API Consumer Key as the username and the REST API Consumer Secret as the password». Chiave e segreto viaggiano dentro l'intestazione Authorization.

Quell'intestazione può non arrivare mai. Lo scrive WordPress: «If you're finding that you are sending Authentication headers but the request is not being accepted, and you are using a CGI environment, your webserver may be stripping the headers». Attenzione al verbo: può toglierle. WordPress non dice quanto succeda spesso, e non lo diciamo nemmeno noi.

Il passaggio la fonte non lo descrive, ma è così che si spiega l'errore che vedi: WooCommerce riceve una richiesta senza credenziali e si lamenta della cosa che non ha trovato, la chiave. Da fuori sembra sbagliata. Non c'è proprio.

WordPress dà anche le due righe che la rimettono a posto. Su Apache, dentro <IfModule mod_setenvif>: SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1. Su Nginx, nella sezione fastcgi: fastcgi_pass_header Authorization;. Se non sei tu a toccare il server, sono le righe da girare a chi ti gestisce l'hosting: in quale file vadano messe le pagine ufficiali non lo dicono, e dipende da come è configurata la tua installazione.

E c'è un rimedio che non richiede di toccare niente, sulla pagina Authentication di WooCommerce: «In this case, you may provide the consumer key/secret as query string parameters instead». Chiave e segreto nell'indirizzo, invece che nell'intestazione. Funziona perché nel codice le credenziali si cercano in ordine — prima i parametri consumer_key e consumer_secret nell'indirizzo, poi quelli della Basic Auth, poi quelli OAuth — e il primo posto in cui guarda è l'unico che non passa dall'intestazione sparita.

Ramo 2 — l'indirizzo non esiste (e non è WooCommerce a dirtelo)

Questo ramo si riconosce meglio, perché non assomiglia a un problema di credenziali. Fra i requisiti ufficiali dell'API REST di WooCommerce c'è scritto: «Pretty permalinks in Settings > Permalinks so that the custom endpoints are supported. Default permalinks will not work».

Il motivo lo spiega WordPress, non WooCommerce: «For sites without “pretty permalinks” enabled, /wp-json/ isn't automatically handled by WordPress». Con i permalink su Semplice, /wp-json/ non è una rotta. Non esiste. La richiesta non arriva mai a WooCommerce, quindi quello che ti torna non è una risposta di WooCommerce sulla chiave: è un 404 del sito.

Se cambi la chiave dieci volte e non si muove niente, può darsi che nessuna delle dieci sia mai stata letta. La stessa pagina di WordPress documenta l'altra forma dell'indirizzo, ?rest_route=/.

Ramo 3 — manca la S di https

Qui la chiave non viene rifiutata: non viene letta come credenziale Basic. Su HTTP semplice «You must use OAuth 1.0a “one-legged” authentication to ensure REST API credentials cannot be intercepted by an attacker». E il codice ufficiale conferma che sono due strade separate: la classe di autenticazione esegue «OAuth 1.0a “one-legged” authentication for non-SSL requests».

Sull'altra strada, quella cifrata, la connessione sicura rende inutile la firma, quindi «the request can be authenticated by simply looking up the user associated with the given consumer key and confirming the consumer secret provided is valid». Due percorsi, due modi di fallire, due messaggi.

Il quarto caso, quello che si legge da solo

Quando crei la chiave scegli anche cosa può fare, e le possibilità sono tre: «Read access, Write access or Read/Write access». Il codice ufficiale mappa i metodi HTTP sui permessi: HEAD e GET richiedono la lettura, POST, PUT, PATCH e DELETE la scrittura, OPTIONS è sempre consentito. Una chiave di sola lettura legge il catalogo benissimo e fallisce qualunque tentativo di creare o modificare.

Questo caso però non si traveste da problema di chiave: nel codice ha messaggi suoi ed espliciti — «The API key provided does not have write permissions.», con il gemello per la lettura. Se leggi una frase così, la diagnosi è già finita.

La tabella da tenere aperta

Aiuta sapere che forma ha la risposta: le API restituiscono «both an appropriate HTTP status code and response object which contains a code, message and data attribute», con codici di stato 400, 401, 404 e 500. E prima di cercare lontano: i requisiti minimi ufficiali per l'ultima versione dell'API sono WooCommerce 3.5+ e WordPress 4.4+.

Dove entra DropMind, e dove no

Prima il no, che è la parte più grossa. Nessun software di terzi, il nostro compreso, può rimettere un'intestazione che il tuo webserver ha tolto, accendere i permalink al posto tuo o far comparire l'HTTPS su un sito che non ce l'ha: le cause di questo articolo stanno tutte dalla parte del tuo sito. E se hai un negozio tuo, sai scrivere due righe di codice e ti serve solo leggere gli ordini, non devi comprare niente: l'API REST è documentata e gratuita.

Quello che facciamo noi è a valle. WooCommerce è uno dei cinque canali su cui DropMind pubblica — con eBay, Shopify, Etsy e BigCommerce — ed è anche una delle due piattaforme che riconosciamo quando importi da un negozio qualsiasi, per usare la sua strada ufficiale invece di leggere la pagina. Il collegamento lo fai una volta sola: questo pezzo serve perché quella volta lì vada liscia.

Da dove vengono questi fatti

Ogni frase fra virgolette è presa dalle pagine qui sotto, lette il 1° settembre 2026: documentazione dell'API REST di WooCommerce, manuale dell'API REST di WordPress, codice della classe di autenticazione nel repository ufficiale. Nient'altro — i nomi dei plugin che toglierebbero l'intestazione, per dirne una, non compaiono in nessuna fonte ufficiale, quindi qui non li trovi.

Due limiti dichiarati. Nessuna di queste pagine mette le cause in classifica per frequenza, quindi non sappiamo — e non scriviamo — quale sia «la più comune». E questa documentazione viene riscritta spesso: se una riga di qui decide qualcosa per te, apri la fonte e controlla che ci sia ancora.