Why does my WooCommerce API key return 401?
Over HTTPS the WooCommerce REST API takes basic auth: consumer key as username, consumer secret as password. When the server does not pass that header to PHP, WooCommerce sees no credentials and reports that the consumer key is missing, which is not a bad key. Pass the Authorization header through, or send key and secret as query parameters.
Read the error before you reissue the key
Only the first row is really an authentication problem, and even that one is a server configuration problem wearing an authentication message. Work out which row you are in before you start regenerating keys, because a fresh key fails the same way.
| What you see | Most likely cause | What to change |
|---|---|---|
| Consumer key is missing | Over HTTPS, the server did not parse the Authorization header | Pass the header through, or use query string parameters |
| Invalid signature, over HTTP | OAuth 1.0a signature built wrong | Check the signature base string, or move the store to HTTPS |
| 404 rest_no_route | Permalinks, not credentials | Set permalinks to anything but Plain and re-save |
| Reads work, writes refused | The key was issued with Read permission | Revoke it and generate a Read/Write key |
Fix the stripped Authorization header
In CGI environments the web server can drop the authentication header before PHP sees it. The WordPress REST API handbook gives the pass-through rule for both common servers.
On Apache, add to a config file or .htaccess: <IfModule mod_setenvif> SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 </IfModule>
On Nginx, add fastcgi_pass_header Authorization; to the fastcgi section of your server config.
Reload the server, then retry the same authenticated request.
The same handbook notes an Nginx try_files line that drops query arguments. If your query string parameters vanish too, that is the rule to look at.
The query string fallback
WooCommerce documents the escape hatch directly: when some servers do not parse the Authorization header correctly, you may provide the consumer key and secret as query string parameters instead. It is the right immediate move when you cannot touch the server config, and it is worth knowing that the credentials then sit in the URL, so they can end up in access logs.
Over plain HTTP the rules change
Basic auth with key and secret is the HTTPS method. Over HTTP the WooCommerce REST API requires OAuth 1.0a one-legged authentication, which means building a normalised parameter string, a signature base string and an HMAC-SHA1 signature. Most integrations will not do this, so a store that is not on HTTPS is usually the underlying issue rather than the key.
When it is genuinely the key
Two cases are real credential faults. The consumer secret was shown once at generation and may have been copied short or with whitespace.
And the key may have been revoked from WooCommerce > Settings > Advanced > REST API, where every key has a Revoke Key link. In both cases generate a new Read/Write key, copy the secret carefully, and retest with a single GET to /wp-json/wc/v3/orders.
Key takeaways
- Consumer key is missing over HTTPS is a stripped Authorization header, not a bad key.
- Apache needs the SetEnvIf rule; Nginx needs fastcgi_pass_header Authorization.
- WooCommerce supports key and secret as query string parameters as a fallback.
- A Read key authenticates fine and still refuses to update an order.
How the connection is verified
I'd Ship That for WooCommerce is in early access, and connecting means pasting your site URL with a REST API consumer key and secret. We verify the pair against your store before storing it, so a stripped header or a Read-only key is caught at connect time instead of at write-back time. After that, orders arrive in The Workbench on a scheduled sync and buying a label sets the order to completed with tracking.
Related questions
Treat it as a fallback rather than a setup. WooCommerce documents query string parameters for servers that will not pass the Authorization header, but the credentials then travel in the URL and land in logs. Fixing the header pass-through is the durable answer.
Not usually. A revoked key is a credential that no longer exists, while consumer key is missing means WooCommerce received no credential at all. Check the REST API screen for the key by description before regenerating anything.
Different clients send credentials differently. One may use basic auth, which depends on the header surviving, and another may append query string parameters, which does not. That split is the clearest sign you are looking at a header pass-through problem.
Read/Write. Reading orders needs Read, and setting an order to completed with tracking meta needs Write, so a key that only reads will import your queue and then fail on the write back.