Remove "403 INVALID_TOKEN_CONTEXT" error

[fernandopradocabrillo]

Problem description

As of now, kyc-match is the only CAMARA API that is not following the agreed standar for the API errors defined in COMONALITIES.
The error 403 INVALID_TOKEN_CONTEXT allows to mimic the functionality of Number Verification's /verify endpoint and is a challenge from the implementation perspective as it is the only CAMARA API that implements this error so it increases the effort to standarize the error handling and from a commercial point of view, as it should be carefully marketed in regard to number verification to avoid obtaining this functionality more cheaply.

In my opinion we should discuss this topic before we talk about going for a stable version

Possible evolution

Remove the error and update with the spec with the commonalities agreed errors

[PaoloCommissari]

Hi @FabrizioMoggio @GillesInnov35 @ToshiWakayama-KDDI @giuseppe-costanzo @gcarotenuto

this issue is very important. TIM agrees to align the KYC behavior with the commonalities by returning the error GENERIC_422_UNNECESSARY_IDENTIFIER (status 422, code UNNECESSARY_IDENTIFIER, message: “The device is already identified by the access token.”).

This response must be returned when an explicit phone number is included in the payload, while the device has already been identified through the access token.

BR,

P.

[FabrizioMoggio]

Hi @FabrizioMoggio @GillesInnov35 @ToshiWakayama-KDDI @giuseppe-costanzo @gcarotenuto

this issue is very important. TIM agrees to align the KYC behavior with the commonalities by returning the error GENERIC_422_UNNECESSARY_IDENTIFIER (status 422, code UNNECESSARY_IDENTIFIER, message: “The device is already identified by the access token.”).

This response must be returned when an explicit phone number is included in the payload, while the device has already been identified through the access token.

BR,

P.

I totally support @PaoloCommissari proposal to adopt 422 code for this use case as specified by https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml .

[GillesInnov35]

@fernandopradocabrillo , you're right, I think we should create the coresponding PR to align specs with Commonalities.
Thanks
Gilles

[ToshiWakayama-KDDI]

Thank you, @fernandopradocabrillo , @PaoloCommissari , @FabrizioMoggio , @GillesInnov35 ,

Sorry that I have not commented to this issue so far.

As you know, this has been a long-standing topic with a history of discussion. The current error handling and the optioinal phoneNumber input attribute originate from the first version of the KYC Match API. Subsequently, the Commonalities working group discussed related error handling and established the current 422 error. We were involved in that discussion, and the group allowed us to keep our existing error handling implementation and the phoneNumber input.

Please also find the following issues in the KYC old repository (https://github.com/camaraproject/KnowYourCustomer):
Issue #189 in the old repo (camaraproject/KnowYourCustomer#189)
Issue #213 in the old repo (camaraproject/KnowYourCustomer#213)

Therefore, from KDDI's perspective, we intend to keep the current specifications for backward compatibility and service continuity. We understand it is slightly different from other APIs, but we are proceeding on the basis that the Commpnalities group has allowed this as an exception.

That said, I would still like to hear from others. Other than the different flow and error handling from other APIs, is there any particular problem with our current API specification?

BR

[FabrizioMoggio]

Dear @ToshiWakayama-KDDI, as you can see this issues is raised again. Last time the usage of 422 was maybe new but at this point in time it is a standard and well known behavior. For sure backward compatibility is an important aspect but the alignment with Commonalities for a such relevant API behavior (this is related to the three legs flow) is one of the main characteristic of the CAMARA initiative. I really think that any CAMARA API should be compliant with this first phase of the flaw. The problem is having a different behavior for a part of the flow related to the authentication phase, considering how this phase is always a tricky one.

[GillesInnov35]

@ToshiWakayama-KDDI , as I said I support the aligment with CAMARA Commonalities and the right error code for the concerned scenario.
But I understand also your comment on backward compatibility, it could be an issue if you intend to continuously follow kyc-match API versions. Is it the case for KDDI ?
I think providers will face more and more the issue on API backward compatibility as CAMARA KYC APIs are close to be in a stable status.

[fernandopradocabrillo]

Hi @ToshiWakayama-KDDI, I completely understand your situation here, it's being a long-term discussion within the WG.

I understand that the KYC Match exception may have made sense at the time for bussines purposes, but given the direction CAMARA has taken, I believe the cons outweigh the benefits, especially with the standardisation of errors from Commonalities that have already broken backward compatibility on several occasions. But now it looks like we are in a more stable place in that regard.

1. API Gateway developers must implement special-case logic for KYC Match that differs from every other CAMARA API
2. API consumers must handle different error patterns when using KYC Match vs. other identity-related APIs
3. Testing and validation tools need exceptions for KYC Match
4. Documentation and training materials must explain "why KYC Match is different"

This fragmentation creates friction for the entire CAMARA ecosystem, making it harder to achieve the interoperability goal that CAMARA was created to address.

We already have the API in production in a few markets and dealing with the outdated INVALID_TOKEN_CONTEXT only for this API created some complications for the clients that needed a common interface for all CAMARA APIs.

Like with the removal of the idDocument related errors, the goal is to achieve a normalize behaviour across all implementations.

This issue becaomes more relevant than before now that we are approaching a stable state.

Kind Regards

[ToshiWakayama-KDDI]

Hi @FabrizioMoggio , @GillesInnov35 , @fernandopradocabrillo ,

Thank you for your comments. I talked with my colleagues internally, and we would like to request further discussion on this matter as it has a significant impact on KDDI.

From a technical and implementation standpoint, and from a mobile operator's perspective, we find your points agreeable.

However, we hold a different view from a business perspective and from the API user's point of view. We apologize for repeating our stance, but our understanding is that when an API user wants to retrieve an end-user's basic information (such as name, gender, address, and date of birth), they also want to simultaneously verify that the mobile phone number itself is correct and in use. This is why we believe the phone number should be included in the request. We also assume that other operators in Japan are providing similar KYC APIs.

We understand that the same outcome can be achieved by calling the Number Verification API first, followed by the KYC Match API (without a phone number input). However, we believe that forcing the API user to make two separate calls is not ideal from a usability standpoint.

Therefore, we would like to ask you to please re-confirm with all stakeholders, including the business side of each company, whether the technical/implementation benefit of aligning the KYC Match API with other APIs outweighs the degraded user experience of requiring two API calls.

Thanks,
Toshi

[ToshiWakayama-KDDI]

Hi @fernandopradocabrillo , @GillesInnov35 ,

Sorry for the long delay. I have had difficult discussions internally.

We would still like to seek for a way to keep the phoneNumber input optional for the backward compatibility to the current specification as well as our customers' service-wise benefit.

So, what about this idea?

Most of other operators (API providers) would like to have KYC Match aligned with other APIs in terms of phoneNumber input, i.e. if phoneNumber is included in the request, Error 422 will be returned and the API process will be terminated. KYC Match will adopt this as the default.

As an option, if an operator (API provider) wants, it could accept phoneNumber input in the request, and proceed with the phoneNumber input in the current way, i.e. Error 403 or OK 200.

By doing like this, most operators' implemantion of KYC Match will become the same as that of other APIs, which is requested by the KYC SP's European operators, and just some operators' implementation (like KDDI) will be different and kept as the current implementation.

As for API consumers, as the default, they are supposed to not include phoneNumber in their request, but if some API consumers want to include phoneNumber in their request explicitly to be sent to the operator who can accept phoneNumber, then the request with phoneNumber can be accepted and processed. Those API consumers should be aware of the operators who can accept phoneNumber input. Maybe some prior interaction between the API consumer and the operator is needed.

WDYT？
Or, any questions to my thought?

Best regards,
Toshi

[GillesInnov35]

Hi @ToshiWakayama-KDDI, thanks for your proposition to close this issue. Even if it seems to be a simple option to close the discussion, I'm not sure TSC accepts to allow the API Provider to decide the response code according to the context.
On API Expostion Gateway the API Provider may specify what kind of information it is awaiting. I also wonder how a aggregator could be able to manage 2 different API Provider exposing 2 different API specification/code.
BR
Gilles

[ToshiWakayama-KDDI]

Thanks, @GillesInnov35 .

Let me explain my intention again with additional text.

Most of MNO/API Providers and most of API consumer/aggregators can implement KYC Match in the default way: i.e. phoneNumber must not be included and if included, it will end with a 422 error).

If some specific MNO/API providers cannot adopt the default way because of backward compatibility and businees issues, for example, they are allowed to keep as it is: i.e. if optional phoneNumber is included in the API request, check it with the phoneNumber associated with Access Token. This can be allowed for specific MNO/API providers only, and also for specific API consumers/Aggregators only, and they must have prior negotiation/contract for using the current way.

So, for most of MNO/API providers and most of API consumers/aggregators, this option does not mean anything. This option is only for some specific MNO/API providers and some API consumers/aggregators who explicitly want to use the phoneNumber input, it matters. Furthermore, if an API request does not have phoneNumber input, there will be no difference between most of MNO/API provdiers (with default 422 way) and some specific MNO/API providers (with current way).

In addition, this would be a special treatment temporarily for the backward compatibility issue, and it is expected that those specific MNO/API providers will change their implementation to the default setting eventually.

WDYT?
Please give me any comments, so that we could conclude the issue.

Thanks,
Toshi

[GillesInnov35]

thanks @ToshiWakayama-KDDI for your additional comment.

This option is only for some specific MNO/API providers and some API consumers/aggregators who explicitly want to use the phoneNumber input, it matters.
Am I right if I understand that in that case API Provider doesn't have implemented the API backend in compliance with swagger file ?
To be compliant, the API Provider could continue to expose the previous version.