Clarify RFC 6750 expectations for protected-resource authentication failures on CAMARA service APIs

[jpengar]

Description

Context

During the ICM meeting on April 8th, 2026, we discussed the overlapping between RFC 6750 and CAMARA Commonalities regarding authentication error handling (401/403).

• ICM Meeting Minutes - 2026-04-08
• Clarify RFC 6750 expectations for protected-resource authentication failures on CAMARA service APIs IdentityAndConsentManagement#351 CC @krishnanunnib @Dusty-IAM

---

Current situation

• RFC 6750 defines standard behavior for authentication errors (e.g., WWW-Authenticate header in 401/403 responses) in the protected resource request.
• CAMARA Commonalities defines an additional JSON error format.
• Current requirement:
  → API providers MUST support the CAMARA-defined JSON error body.
• CAMARA does not define anything on top of RFC 6750 regarding the WWW-Authenticate: Bearer header.

---

Identified challenge

• Some architectures (e.g., API gateways) handle authentication errors directly and typically return only RFC-compliant headers.
• Supporting the CAMARA JSON error format requires additional customization.
• Without such customization, implementations may fail CAMARA compliance tests.

At the same time:

• Relaxing the requirement could introduce ambiguity for API consumers, who would not know whether to expect:

  • RFC 6750 headers,
  • CAMARA JSON error body,
  • or both.

---

ICM conclusion

• No change to current requirements was agreed.

• The issue is acknowledged as a valid implementation challenge.

• Further discussion is needed on whether:

  • Requirements should be relaxed, or
  • Additional guidance should be provided.

---

Ask to Commonalities

Since error response formats are defined in Commonalities, this topic requires joint coordination between ICM and Commonalities.

Specifically, we need to clarify:

• Whether the current requirement (mandatory JSON error body) should be maintained or revisited for authentication failures covered by RFC 6750.
• Or whether additional guidance should be provided to ensure consistent implementation without ambiguity.

---

Status

Pending further discussion between ICM and Commonalities.

[rartych]

I think we previously discussed that standard error responses for OAuth2 do not have to be reformated to Error Info, but indeed we do not have it documented in the guidelines.

Possible solution is layered approach:

Layer	Who handles it	Baseline standard	CAMARA JSON body
Token validation (missing, expired, malformed Bearer)	API gateway / security proxy	RFC 6750	SHOULD (or explicitly optional)
Authorization / business logic (scope mismatch, consent denied)	CAMARA service API	CAMARA Commonalities	MUST

Could it be easily distinguished with diffrent implementation architectures and in compliance tests?

[jpengar]

From Telefónica's perspective, we advocate for maintaining and explicitly documenting the current CAMARA requirement, which states that 401 and 403 errors must include the JSON error body specified by CAMARA.

Our position is based on the following key arguments:

• Avoidance of Fragmentation for API Consumers: Allowing API Providers to return only the WWW-Authenticate header without the CAMARA-defined JSON body would shift the burden of complexity to the API Consumer. Developers would face fragmentation, needing to implement different logic for error handling depending on the specific API Provider’s implementation.
• Enhanced Interoperability: We believe that true interoperability is achieved by ensuring a common, predictable behavior across all CAMARA APIs. Having a consistent JSON body for all error codes (including 401 and 403) is fundamental for a uniform developer experience.
• Impact on GSMA Certifications: The current GSMA Open Gateway certification test suites expect error responses to follow the format specified by CAMARA. Removing the requirement for a JSON body in 401/403 errors would directly conflict with these certification processes and require significant rework of the compliance criteria.
• Risk of Breaking Changes: Since the CAMARA error format has been the standard to date, many existing consumers already rely on receiving this potentially mandatory JSON body. Moving away from this would constitute a breaking change for those integrations.
• Justification for the Change: Unless there is evidence of a widespread, technical inability to support this within major commercial API Gateway solutions, we do not believe a breaking change to the standard is justified given the negative impacts mentioned above.

It is worth noting that Telefónica’s implementation currently complies with both requirements: we provide the CAMARA-defined JSON body and adhere to RFC 6750 (including the WWW-Authenticate header).

e.g.

HTTP/2.0 401 Unauthorized
content-type: application/json; charset=utf-8
content-length: 69
www-authenticate: Bearer realm="fp",error="invalid_token",error_description="No token provided"
x-correlator: 64834c2d-004d-448e-9387-1472900f15de
{"status":401,"message":"No token provided","code":"UNAUTHENTICATED"}

Proposal:
Instead of making the JSON body optional, we propose to explicitly document a clarification in the "Commonalities" documentation.

CC @PedroDiez

[Dusty-IAM]

Hi @jpengar ,

Thanks again for the response and for continuing to follow this topic.

From my perspective, this is not only about technical possibility. It is mainly about whether this is desirable in deployments where token handling is separated from application logic. Making a JSON body mandatory for token-validation failures means introducing API-specific behavior into the gateway/security layer. Even if that is technically possible, it is not always wanted, and in some environments it can also be limited by security or operational governance.

I can see why keeping this consistent for CAMARA consumers is important, especially if certification and existing integrations already depend on it. My point is just that there is also a broader interoperability and implementation tradeoff when protected-resource token handling moves away from the RFC 6750 model that many gateways and integrations already rely on.

The main point for me is keeping a clear separation between token handling and application/API behavior. For protected-resource calls using Bearer access tokens, RFC 6750 already provides a well-known model for authentication failures through the HTTP status code and the WWW-Authenticate challenge. Keeping the JSON body optional, or at least not assuming it for token handling, makes that separation easier to maintain.

I also think the impact is broader than interoperability between API providers alone. It affects integrators as well, because it influences whether CAMARA APIs can continue to follow the same protected-resource patterns and tooling that are already common across other OAuth-protected APIs. The more specific CAMARA becomes in this area, the more additional handling is needed around something that is otherwise already standardized.

My preferred direction would still be the layered approach suggested by @rartych . If the group prefers to keep the current requirement, I think it would still help to document this more explicitly as an implementation risk, because this kind of boundary can be easy to overlook, especially when token handling and API implementation sit in different components or teams.

[PedroDiez]

I think it is relevant to have other views within the community, this topic has several important implications and would be needed as much consensus as possible