WWW-Authenticate

Sends username and password Base64-encoded on every request. Base64 is not encryption — anyone who intercepts the header reads the password in plain text.

WWW-Authenticate: Basic realm="demo"

• ·Instantly reversible: atob("dXNlcjpwYXNzd29yZA==") → "user:password".
• ·Requires HTTPS at all times; without TLS the credential travels in the clear.
• ·No expiration or revocation: the credential is valid until the password changes.
• ·The browser shows a native username/password dialog.

Authorization: Basic dXNlcjpwYXNzd29yZA==

Challenge–response scheme: the server sends a nonce and the client replies with a hash, never the password itself. An improvement over Basic, but MD5 is now weak.

WWW-Authenticate: Digest realm="demo", nonce="…", algorithm=MD5, qop="auth"

• ·The password never travels over the network, only a derived hash.
• ·The nonce mitigates replay attacks.
• ·qop="auth" also protects the HTTP method and request URI.
• ·Still depends on MD5/SHA-256; less practical than tokens for APIs.

Authorization: Digest username="user", realm="demo", nonce="…", uri="/demo/digest", response="…", qop=auth, nc=00000001, cnonce="…"

The client carries an access token (often a JWT) issued by an authorization server. "Anyone who holds it can use it" — that's why the token must be protected like a credential.

WWW-Authenticate: Bearer
  realm="demo",
  scope="read write",
  error="invalid_token",
  error_description="The token has expired or is invalid",
  error_uri="https://…/docs/errors/invalid_token"

• ·realm (optional) — protection scope; must not appear more than once.
• ·scope (optional) — space-separated list of required scopes, e.g. "read write".
• ·error (optional) — rejection reason: invalid_request · invalid_token · insufficient_scope.
• ·error_description (optional) — human-readable error explanation, for developers only.
• ·error_uri (optional) — absolute URI pointing to error documentation.
• ·If the token is a JWT, its header and payload are readable (not encrypted) — never store secrets inside.

# The client knows the token endpoint in advance (docs, SDK, config)
→ POST https://auth.example.com/token
   grant_type=client_credentials&scope=read
← 200 { "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600 }

# If the issuer is known, the AS metadata URL is inferred:
→ GET https://auth.example.com/.well-known/oauth-authorization-server
← 200 {
    "token_endpoint": "https://auth.example.com/token",
    "authorization_endpoint": "https://auth.example.com/authorize"
  }
# OIDC fallback if 404:
→ GET https://auth.example.com/.well-known/openid-configuration

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

• ·RFC 6750 does not include the AS URL in the challenge — the client must know it in advance or infer it.
• ·Option A (defined): the token endpoint is configured explicitly in the client (SDK, env var, docs).
• ·Option B (inferred): if the issuer is known, construct /.well-known/oauth-authorization-server per RFC 8414.
• ·For fully automatic discovery from the 401 challenge, use Bearer + Discovery (RFC 9728).

OAuth 2.0 Protected Resource Metadata. The 401 challenge no longer just says "you need a Bearer token": it points to a metadata document describing WHERE and HOW to obtain one. The client discovers everything automatically.

WWW-Authenticate: Bearer resource_metadata="https://…/.well-known/oauth-protected-resource.json"

• ·resource_metadata — the only challenge parameter; URL of the resource metadata document.
• ·The client extracts authorization_servers[0] as the AS issuer identifier.
• ·Enables generic clients: they discover the full flow from a single 401.
• ·Key for ecosystems like agents and MCP, where the client does not know the issuer in advance.

← 401 WWW-Authenticate: Bearer resource_metadata="https://…/.well-known/oauth-protected-resource.json"

→ GET https://…/.well-known/oauth-protected-resource.json
← 200 {
    "resource": "https://…/demo/bearer2",
    "authorization_servers": ["https://auth.example.com"],
    "scopes_supported": ["read", "write"]
  }

→ GET https://auth.example.com/.well-known/oauth-authorization-server
← 200 {
    "issuer": "https://auth.example.com",
    "authorization_endpoint": "https://auth.example.com/authorize",
    "token_endpoint": "https://auth.example.com/token",
    "scopes_supported": ["read", "write"],
    "grant_types_supported": ["authorization_code", "client_credentials"]
  }

→ GET https://auth.example.com/.well-known/openid-configuration
← 200 {
    "issuer": "https://auth.example.com",
    "authorization_endpoint": "https://auth.example.com/authorize",
    "token_endpoint": "https://auth.example.com/token",
    "userinfo_endpoint": "https://auth.example.com/userinfo",
    "jwks_uri": "https://auth.example.com/jwks"
  }

→ POST https://auth.example.com/token
← 200 { "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600 }

→ GET https://…/demo/bearer2
   Authorization: Bearer eyJ…
← 200 OK

• ·Step 3a — RFC 8414: looks up /.well-known/oauth-authorization-server[/{path}] using the issuer.
• ·Step 3b — If 404, falls back to OpenID Connect Discovery: /.well-known/openid-configuration.
• ·URL construction follows the same rule: well-known inserted between the host and path of the issuer.
• ·The AS document exposes authorization_endpoint, token_endpoint, scopes_supported, grant_types…
• ·With those endpoints the client completes the OAuth flow and obtains a valid Bearer token.