A 401 Unauthorized error means the server requires authentication and the request either did not include credentials, or the credentials provided are invalid. In modern HTTPS APIs and microservices, 401 errors are increasingly caused by missing or invalid client certificates in mutual TLS (mTLS) setups – not just missing usernames and passwords.
What Causes a 401 Unauthorized Error?
A 401 error has a single root cause: the server could not verify who is making the request. According to the MDN HTTP 401 status code reference (updated July 2025), the server always sends a WWW-Authenticate response header that tells the client exactly which authentication scheme it expects.
The table below maps every common 401 trigger. Blue rows are certificate-related causes unique to mTLS setups – these are the ones most other 401 guides miss.
| Cause | Who it affects | Category | Quick fix |
| Missing login credentials | Website visitors | Auth | Log in or create an account |
| Expired session / cookie | Website visitors | Session | Clear cookies and log in again |
| Invalid API key or token | Developers | API | Regenerate API key in provider dashboard |
| Expired JWT token | Developers | API | Refresh or reissue the token |
| Wrong Authorization header format | Developers | API | Check Bearer vs Basic vs API-Key format |
| Missing client certificate (mTLS) | API / microservice devs | mTLS | Attach correct client cert to request |
| Expired client certificate | API / microservice devs | mTLS | Renew cert and redeploy to client app |
| Wrong or untrusted CA | API / microservice devs | mTLS | Use cert signed by a CA the server trusts |
The certificate-related causes (bottom three rows) appear when both parties must authenticate – not just the server. This differs from standard HTTPS, where only the server presents a certificate.
How Do You Fix 401 Unauthorized as a Website Visitor?
Website visitors hitting a 401 almost always have a session or credential problem. The fix is typically one of the following five steps.
- Log in to the website. A 401 means the page requires authentication – not that your account is banned. Navigate to the login page and sign in with your credentials.
- Clear browser cookies and cache. Session cookies expire, and an outdated cookie can trigger a 401 even when your credentials are correct. Clear site data in your browser settings and try again.
- Check whether the URL requires a login. Some pages are intentionally private. If the URL contains /account/, /dashboard/, or /admin/, it is likely behind a login wall.
- Disable browser extensions. Ad blockers and privacy extensions occasionally strip the Authorization header from outgoing requests. Try loading the page in an incognito window to isolate this.
- Contact the site owner. If you should have access and none of the above works, the site may have revoked your credentials or have a server-side authentication misconfiguration.
How Do You Fix 401 Unauthorized in an API?
For developers, a 401 from an API nearly always points to an authentication header problem. Check these fixes in order before investigating anything else.
- Check your Authorization header format. The format matters: Bearer <token> for OAuth/JWT, Basic base64(user:pass) for Basic Auth, and X-API-Key: <key> for API-key schemes. A wrong format returns 401 even with valid credentials.
- Verify your API key is active. API keys expire or get rotated. Open your provider’s developer dashboard and confirm the key is active. Regenerate it if there is any doubt.
- Inspect your JWT token’s expiry. Decode the token at io token debugger and check the exp claim. An expired JWT always returns 401. Refresh or reissue the token.
- Check OAuth 2.0 token scope. A valid token with the wrong scope returns 401 when accessing a resource that requires a permission the token was not issued for. Request a new token with the correct scopes.
- In Postman, set the Authorization tab correctly. Go to the Authorization tab, select the correct type (Bearer Token, Basic Auth, API Key, or OAuth 2.0), and enter your credentials. Never paste credentials directly into the URL.
What Is mTLS and Why Does It Cause 401?
Mutual TLS (mTLS) is an extension of standard TLS where both the server and the client present X.509 certificates during the handshake. When a server is configured to require a client certificate and the request arrives without one, the server returns 401 Unauthorized – not a TLS error.
mTLS is specified in RFC 8705 – OAuth 2.0 Mutual-TLS Client Authentication (IETF, February 2020). It is standard in zero-trust network architectures, internal microservice meshes (Istio, Linkerd, Consul Connect), and financial-grade APIs. Understanding the mutual TLS handshake process helps clarify exactly where authentication fails.
The key distinction: standard HTTPS authenticates the server to the client. mTLS requires the client to prove its identity too. Without a valid client certificate, the connection either fails at the TLS layer or the application layer returns 401.
How Do You Fix 401 in curl with a Client Certificate?
If curl returns 401 without a certificate flag but returns 200 when you add one, the endpoint requires mTLS. Use the appropriate format for your certificate type.
| Certificate Format | curl Command | Notes |
| Separate .crt + .key files | curl –cert client.crt –key client.key https://api.example.com | Most common format |
| Combined PEM file | curl –cert combined.pem https://api.example.com | Cert + key in single file |
| PKCS12 (.p12) file | curl -E client.p12:password https://api.example.com | Password-protected container |
Always test with verbose output first: add -v to see the TLS handshake details and confirm whether a client certificate was requested.
How Do You Fix 401 in Python requests with a Client Certificate?
Pass certificate paths via the cert parameter. The requests library handles the TLS negotiation automatically once you specify where the certificate files live.
- Separate cert and key: requests.get(url, cert=(‘client.crt’, ‘client.key’))
- Combined PEM file: requests.get(url, cert=’combined.pem’)
- Verify with custom CA bundle: requests.get(url, cert=(‘client.crt’, ‘client.key’), verify=’ca-bundle.crt’)
If the server uses a private CA, set verify to your CA bundle path rather than True. Setting verify=False disables certificate validation entirely and should never be used in production.
How Do You Fix 401 in Postman with a Client Certificate?
Postman handles client certificates through a dedicated settings panel – not the Authorization tab. The process takes under two minutes.
- Open Postman Settings (gear icon, top right).
- Go to the Certificates tab.
- Click Add Certificate and enter the host (e.g., api.example.com), port (443), and your certificate file paths.
- Send the request. A 200 response confirms the certificate was accepted. A 401 still means the cert is wrong or expired.
How Do You Fix 401 in Nginx mTLS Configuration?
Server-side 401 errors from Nginx’s client certificate authentication setup usually come from three directives in your server block.
- ssl_verify_client on; – Nginx requires a client certificate. Requests without one return 400 or 401 depending on the application layer handling.
- ssl_client_certificate /path/to/ca.crt; – Points to the CA that signed your client certificates. If the path is wrong or the CA is missing, all client certificates are rejected.
- 401 vs 403 distinction: Nginx itself returns 400 when no cert is presented at the TLS layer. A 401 at the HTTP layer means your application received the connection but rejected the credential – check application-level auth logic separately.
Common mTLS Certificate Errors That Return 401
Each of these error conditions produces a 401 for a different reason. Matching the symptom to the cause reduces debugging time significantly.
| Error Condition | Root Cause & Fix |
| No client certificate presented | Client did not attach a cert. Add –cert flag in curl or configure client cert in your HTTP client. |
| Certificate signed by unknown CA | Server’s CA bundle doesn’t include the CA that signed your cert. Add your CA’s root certificate to the server’s trusted CA list. |
| Client certificate expired | Cert passed its Not After date. Renew the certificate and redeploy it to all client applications. |
| Wrong certificate for endpoint | Each service in a zero-trust mesh may require a different cert. Verify the cert is scoped for the specific endpoint. |
openssl s_client -connect api.example.com:443 -cert client.crt -key client.key
How Do You Fix 401 on Specific Platforms?
Some platforms add their own authentication layers on top of standard HTTP auth. The fix depends on which platform is returning the 401.
401 Unauthorized on WordPress
- REST API requests to /wp-json/ require Application Passwords (introduced in WordPress 5.6). Generate one under Users → Profile and pass it as Basic Auth credentials.
- JWT authentication plugin misconfiguration is a common cause. Verify the secret key in wp-config.php matches what the plugin expects.
- If your REST API returns 401 for all endpoints, check whether your permalink structure is set to anything other than Plain under Settings → Permalinks.
401 Unauthorized on AWS API Gateway
- A missing or expired Cognito token is the most frequent cause. Use the AWS SDK to refresh the token or call the Cognito endpoint to obtain a new one.
- API keys must be attached to a Usage Plan and the plan must be associated with the stage. An API key that exists but is not linked to a plan returns 403, not 401 – check both.
- For IAM authorization, the request signature must use SigV4. A missing or malformed Signature header triggers 401 on IAM-protected endpoints.
401 Unauthorized in Nginx
- auth_basic misconfiguration is the leading cause. Verify the auth_basic_user_file path is absolute and the .htpasswd file exists at that exact location.
- Passwords in the .htpasswd file must be hashed with htpasswd -B. Plain-text passwords are not accepted by modern Nginx builds.
- For mTLS errors, check ssl_verify_client and ssl_client_certificate directives as described above.
Next Steps for Resolving 401 Errors
Start with the simplest explanation: a missing or expired credential. Most 401 errors resolve in under five minutes once you identify whether the problem is a session cookie, an API key, a JWT, or a client certificate. For mTLS issues specifically, testing with curl’s -v flag and openssl s_client gives you direct visibility into the TLS handshake before any application logic runs.
If you are unsure whether the server certificate itself is contributing to the issue, use the SSL Checker Tool to confirm the server certificate chain is valid and trusted. As zero-trust architectures become more common in 2026, certificate-based 401 errors will appear more frequently – so understanding the mTLS layer is now a core debugging skill for any API developer.
Frequently Asked Questions (FAQ)
What is the difference between 401 Unauthorized and 403 Forbidden?
A 401 means the server does not know who you are – authentication is missing or failed. A 403 means the server knows your identity but you lack permission for the requested resource. In practice: 401 means log in first, 403 means you are logged in but still blocked.
Why do I get 401 Unauthorized with a valid SSL certificate?
A valid server SSL certificate authenticates the server to your browser – it has nothing to do with your identity. In mTLS setups, the server also requires a certificate from you (a client certificate). Without it, the server returns 401 even when the HTTPS connection is fully encrypted and the server certificate is valid.
Can an expired SSL certificate cause a 401 error?
An expired server SSL certificate causes ERR_CERT_DATE_INVALID in the browser – not a 401. However, an expired client certificate in an mTLS setup causes the server to reject authentication at the application layer and return 401 Unauthorized.
How do I fix 401 Unauthorized in Postman?
Go to the Authorization tab and choose the correct type (Bearer Token, Basic Auth, API Key, or OAuth 2.0). For mTLS endpoints, go to Settings → Certificates, add your client certificate for the host, then resend. A missing client cert is a separate issue from a missing auth token.
What does 401 Unauthorized mean in a REST API?
The request reached the API but lacked valid authentication. Check that the Authorization header is present, formatted correctly, and contains a non-expired credential – whether that is a Bearer token, an API key, or a client certificate depending on what the API requires.
What causes 401 with a valid client certificate?
Even with a valid client certificate, the server returns 401 if the certificate was signed by a CA the server does not trust, if the certificate has been revoked, or if the certificate does not match the subject expected by the server. Check the ssl_client_certificate path on the server and verify the CA chain is complete.
Priya Mervana
Verified Web Security Experts
Priya Mervana is working at SSLInsights.com as a web security expert with over 10 years of experience writing about encryption, SSL certificates, and online privacy. She aims to make complex security topics easily understandable for everyday internet users.
