HTTP 401 Unauthorized means the request was rejected because it lacks valid authentication credentials. The server is saying 'I do not know who you are — prove your identity before I give you access.' This happens when no credentials are sent at all, when the username or password is wrong (Basic Auth), when a bearer token is missing or expired (OAuth/JWT), or when an API key is invalid. The server always includes a WWW-Authenticate response header that tells the client which authentication scheme to use — check this header first, as it is the key to understanding what the server expects.
The request did not include an Authorization header, or it included Basic Auth credentials (username:password base64-encoded) that are incorrect. This is the most common cause when accessing password-protected pages, admin panels, or APIs that use Basic Authentication. The username or password may have been changed, or the base64 encoding may be malformed.
The request did not include a Bearer token in the Authorization header, or the token has expired. OAuth2 access tokens are typically short-lived (1 hour for most providers). JWT tokens have an expiration claim (exp) that the server checks. Once expired, the client must obtain a new token using a refresh token or by re-authenticating.
The API key sent in the request header, query parameter, or request body is not recognized by the server. The key may have been deleted, regenerated, or deactivated by the API provider. Some APIs pass the key via an X-API-Key header, others use a query parameter like ?api_key=, and others expect it in the Authorization header.
The server expects one authentication method but received a different one. For example, the server requires a Bearer token but the client sent Basic Auth credentials, or the server expects an API key header but the client sent a Bearer token. The WWW-Authenticate response header tells you exactly which scheme the server expects.
The credentials are valid but were sent to the wrong server — for example, using production credentials against the staging API, or test API keys against the production endpoint. Each environment typically has its own set of credentials.
Send a request without credentials and inspect the response. The WWW-Authenticate header tells you the authentication scheme the server expects. Look for 'Basic' (username/password), 'Bearer' (OAuth/JWT token), or a custom scheme. This is the single most important step — everything else depends on which scheme the server uses.
curl -I https://api.example.com/v1/users
If the WWW-Authenticate header says 'Basic', the server expects a username and password. Curl's -u flag handles the base64 encoding for you. Verify the username and password are correct — these are usually provided by the service administrator or found in your account settings. Basic Auth sends credentials with every request, so always use HTTPS.
curl -u username:password https://api.example.com/v1/users
If the WWW-Authenticate header says 'Bearer', the server expects an access token. You get this token from the provider's OAuth flow or authentication endpoint. Include it in the Authorization header. If the token is expired (the error response may include 'token_expired'), you need to refresh it or obtain a new one.
curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' https://api.example.com/v1/users
If the service uses API key authentication, check the API documentation for where the key should go — common locations are the X-API-Key header, an Authorization header, or a query parameter. API keys are typically found in your account dashboard or developer settings. If the key was recently regenerated, update it in your application.
curl -H 'X-API-Key: your_api_key_here' https://api.example.com/v1/users
If using OAuth2 and your access token has expired, use the refresh token to get a new one from the provider's token endpoint. The refresh token is long-lived and was issued alongside the original access token. Store the new access token and retry your request.
curl -X POST https://auth.example.com/oauth/token -d 'grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'
Confirm the API URL matches the environment your credentials belong to. Production, staging, and development environments have separate credential sets. Check the base URL, API version, and any environment-specific headers your service requires.