API misuse

[AxelNennker]

Problem description
@HuubAppelboom raised an issue in today's SimSwap... - meeting

@HuubAppelboom raised a good point about potential use of SIM swap to perform a numberVerification

If the parameter phoneNumber is present and the phoneNumber is also in the access token, then SimSwap might also accidentally implementing NumberVerification because if the values do not match the result of the API request is different to when the values match.

This problem exists for APIs where identifying information is available in several places.

This leads to several topics worth considering:

• APIs are not "atomic"
• Privacy considerations because an API (e.g. SimSwap) is leaking information
• Legal considerations because API access was granted for one "purpose" which might might match or might not match the "emulated" API access
• Business implications because clients who bought one API (e.g. SimSwap) do not need to buy the emulated API (e.g. NumberVerification)

Expected behavior
API Design Guideline should make API designers aware of this problem and provide guidance on how to handle this.

e.g. add guidance e.g. to the API Design Guidelines' Security section like the following sentence
If identifying information is both available in a request parameter and in the access token then the resource server MUST ignore the request parameter. No error should be returned if information from the access token and information from request parameters are inconsistent or contradict each other, because the error message is doing the leaking of information.

ICM could also or additionally put some text into info.description?! @jpengar

Aditional Context

regarding device object:
camaraproject/DeviceLocation#201

[jpengar]

This issue is trickier than it looks. IMHO, this would only apply if the access token was obtained using Auth Code, where the phone number is validated with network-based authentication. In the case of CIBA, the phone number is provided by a backend as login_hint.

On the other hand, if the API request provides a phone_number, it must be validated against the access token to ensure that the client is allowed to access the requested resource, i.e., the client can only access the authenticated phone number associated with the access token.

I understand the proposed guideline text as potential solution, but it could also be misleading for the API client that (for example) if I request the location of phone number B with the access token associated with phone number A, I will not get an error, but a success response and the actual location obtained is the one corresponding to phone number A.

I think this needs further discussion in the WG...

• So far CAMARA only recommends not to send the device object in the API request when using 3-legged access tokens, should CAMARA make it mandatory? In case of SIM swap it was decided to follow the same Commonalities recommendation for device object but with the phoneNumber field (Extracting phoneNumber from the 3-legg access token SimSwap#117).
• Should the API document instead, as suggested, that the phone number is ignored in the request when using 3-legged access tokens? Is it a good experience from the API client perspective to not get an error and get the information of a phone number different from the one requested?

[patrice-conil]

Hi @jpengar,
I agree with You it's trickier than it looks.

This issue is trickier than it looks. IMHO, this would only apply if the access token was obtained using Auth Code, where the phone number is validated with network-based authentication. In the case of CIBA, the phone number is provided by a backend as login_hint.

On the other hand, if the API request provides a phone_number, it must be validated against the access token to ensure that the client is allowed to access the requested resource, i.e., the client can only access the authenticated phone number associated with the access token.

I understand the proposed guideline text as potential solution, but it could also be misleading for the API client that (for example) if I request the location of phone number B with the access token associated with phone number A, I will not get an error, but a success response and the actual location obtained is the one corresponding to phone number A.

I think this needs further discussion in the WG...

• So far CAMARA only recommends not to send the device object in the API request when using 3-legged access tokens, should CAMARA make it mandatory? In case of SIM swap it was decided to follow the same Commonalities recommendation for device object but with the phoneNumber field (Extracting phoneNumber from the 3-legg access token SimSwap#117).

This is probably the best option in my opinion. Because we need to avoid having conflicting sources of information and it seems to be the best way to ensure that personal information is not disclosed.

• Should the API document instead, as suggested, that the phone number is ignored in the request when using 3-legged access tokens? Is it a good experience from the API client perspective to not get an error and get the information of a phone number different from the one requested?

I think this would be source of confusion. If we have info twice we must check they match and return an error if not.

[sfnuser]

If the parameter phoneNumber is present and the phoneNumber is also in the access token, then SimSwap might also accidentally implementing NumberVerification because if the values do not match the result of the API request is different to when the values match.

What would be the use case where SimSwap API access requires a 3-legged access token? Why would a fraudulent user ever allow 3-legged token to proceed?

This problem exists for APIs where identifying information is available in several places.

This leads to several topics worth considering:

• APIs are not "atomic"
• Privacy considerations because an API (e.g. SimSwap) is leaking information
• Legal considerations because API access was granted for one "purpose" which might might match or might not match the "emulated" API access
• Business implications because clients who bought one API (e.g. SimSwap) do not need to buy the emulated API (e.g. NumberVerification)

Should we consider DEVICE_IDENTIFIERS_MISMATCH case as well? With one identifier known, can a API consumer verify other identifier?

[AxelNennker]

@jpengar regarding:

This issue is trickier than it looks. IMHO, this would only apply if the access token was obtained using Auth Code, where the phone number is validated with network-based authentication. In the case of CIBA, the phone number is provided by a backend as login_hint.

• client sends CIBA authentication request to telco

• sends SMS with link to login_hint number e.g. https://ciba.telco.com/72522913-b12d-436b-877f-788032d7d11e

• telco responds to client with auth_req_id 1c266114-a1be-4252-8ad1-04986c5b9ac1

• user clicks on link on mobile device https://ciba.telco.com/72522913-b12d-436b-877f-788032d7d11e

• telco authenticates subscriber (using network authentication), collects consent and issues access_token

• client polls telco using auth_req_id 1c266114-a1be-4252-8ad1-04986c5b9ac1

• eventually the telco returns the access token to client

• client sends SimSwap request to telco with access token

The access token is associated with the device/phone_number on which the browser run, that was used to open the link from the SMS.

I think this applies to CIBA.

[eric-murray]

Actually, this is quite straightforward

For CIBA, there is no issue, as both the MSISDN provided in the login_hint field of the /bc-authorize request and any phoneNumber in the service API call are provided by the client. If they provide different numbers, then they deserve to receive an error, which only confirms that they themselves provided different numbers.

And, as I pointed out here, CIBA also effectively allows device IP/port to MSISDN lookup, so there is no reason to use the authorisation code flow if the network supports such an IP to MSISDN mapping capability.

Only if the network is relying on header enrichment to identify the device must the authorisation code flow be used. In Vodafone's case, this will only be for Number Verification, where verifying the MSISDN provided by the client against the true MSISDN is exactly the use case anyway. I can't see us using authorisation code flow for any other API.

[AxelNennker]

This issue is about clients buying SimSwap API but using it for NumberVerification.

If SimSwap is cheaper than NumberVerifcation then clients might buy SimSwap but use it for NumberVerification.
Or if they bought SimSwap but also need NumberVerification, then they might think they skip buying NumberVerfication because SimSwap does verify the number.

The user might have opted-out of NumberVerification but the client is using SimSwap to verify numbers which the user might not have opted-out from.

[eric-murray]

@AxelNennker

But this is inherent to CIBA that supports login_hint="ipport:..." and the use of ID tokens, is it not?

I, as a cheapskate API consumer, request my first access token using login_hint="tel:+1234567890" (the MSISDN the customer tells me) and subsequent access tokens using login_hint="ipport:XX.XX.XX.XX:YYYY". By matching the sub claims of the ID tokens, I can then tell whenever device with MSISDN +1234567890 returns to my application. I don't need to make any service API call at all, I just need to find an API that the end user has opted in to (or not opted out from) and use one of its scopes to request a token.

Or, if I did not know the MSISDN itself but am only interested to know it is the same user returning, I could use CIBA with ipport (or Number Verification) when the end user first visits to obtain a sub for that end user, and then on subsequent device connections use CIBA with ipport for any API with end user consent to confirm whether or not that same end user has returned.

[AxelNennker]

CIBA was designed for use case where the consumption device and the authentication device are different.
https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.6

CIBA was not designed for onboarding a user to a mobile app on the user's smartphone - For that the client's mobile app should use OIDC authorization code flow.
CIBA was not designed for onboarding a user using a webbrowser on a mobile phone - For that the client's webserver should start OIDC authorization code flow in the mobile webbrowser.

CIBA should not be used if consumption device and authentication device are same.
CIBA should not be used if consumption device and authentication device are both under the user's control. (For some definition of control)

The assumptions the client and the telco make about CIBA might not be true or the same.

CIBA and OIDC support login_hint to hint to the authorization server which "account" the user might use to authenticate and give consent. The user is free to use a different account.

CIBA with login_hint=tel:+... shows that the authentication request reached someone at that number.
The assumption that the authentication device has the phone number from login_hint might be true or not.
The assumption that the consumption device has the phone number from login_hint might be true or not.

I always interpreted the NumberVerification documentation that the number is verified when the API request is made, not when the access token is created.
(I removed the link to the NV documentation because NV documentation is now in the yaml file and the linked-to document is stale and probably deprecated. 22.08.2024)

CIBA asserts that someone had control over the authentication device at one point in time.

[HuubAppelboom]

@AxelNennker @eric-murray For API's like KYC Match, SIM Swap and DeviceIdentifier a 3-legged flow is mandatory because we are processing personal information in these. As a result the access token is the access token is phone number specific, and the phone number is already determined by either the login_hint (in case of CIBA) or by retrieving it from the network (in case of front end-flow). There is not point to ask for the phone number again in the resource call (with the exception of Number Verify ofcourse), also because this will lead to either an unintended number verification (in case you start comparing the number provided with the number associated with the access token), or it will lead to confusion with the developer, or it will lead to loss of revenue.

I think there are 3 options:

1. we should either remove the phone numbers from all the resource calls in case only 3 legged flows are permitted
2. we should make the phone number always an optional parameter (to be used only for client credential flows) and always return an error in case the phone number is presented in the resource call with a 3 legged flow (CIBA and Front End Flow)
3. in case the client presents the phone number in the resource call, in case of front end flow, return whether the number matches (just like with Number Verification) , and charge the API consumer additonal charges. In case of CIBA flow, you provide an error in case there is a mismatch between login_hint and the number presented in the resource call.

My preference is option 1, this is the simplest, if you ask me. Option 2 has more flexibility in it, in case parties want to use a (faster) client credential flow.

Would like to hear your thought on this.

[AxelNennker]

@HuubAppelboom from the general issue back to the specific: What do you think about this proposal?
camaraproject/SimSwap#117 (comment)
which seem to cover your option 2 and 3

[eric-murray]

@HuubAppelboom

and the phone number is already determined by either the login_hint (in case of CIBA)

In the case of CIBA, the phone number is specified by the API consumer, independent of any end user device. If the API consumer then specifies a different phone number in the API service call itself, then any error is just telling them that they specified two different end user phone numbers. I don't see the issue here, as no device has ever confirmed its phone number.

I can see the issue with authorisation code flow but, for APIs such as SIM Swap, using authorisation code flow doesn't really make sense for the use case. Current implementations use CIBA. This will be true for many APIs.

@AxelNennker
How does the proposed solution for SIM Swap fix the issues with CIBA and use of login_hint="ipport:..."?

[jpengar]

@eric-murray I think that assuming only the use of CIBA flow for 3-legged scenarios is something we shouldn't do (there's not even consensus about it CC @sfnuser @AxelNennker ) and IMHO it's not consistent with existing CAMARA definitions in ICM. It has its own discussion thread in camaraproject/IdentityAndConsentManagement#176 as you mention. So I would not consider it a solution to the original problem reported here.

From Huub's comment, I see option 2 as the one that better fits exiting ICM definitions giving the flexibility to consume and API in 3-legged and 2 legged mode as needed.

we should make the phone number always an optional parameter (to be used only for client credential flows) and always return an error in case the phone number is presented in the resource call with a 3 legged flow (CIBA and Front End Flow)

We should make sure that there are no other corner cases not considered so far if option 2 is chosen. And it would be necessary to define what would be the error returned to the API client when phone_number/device is used in the API call with a three-legged flow.

[HuubAppelboom]

@HuubAppelboom from the general issue back to the specific: What do you think about this proposal? camaraproject/SimSwap#117 (comment) which seem to cover your option 2 and 3

@AxelNennker The problem with this proposal is that once you provide errors like the 403 - INVALID_TOKEN_CONTEXT error, you are effectively doing the same thing as a in a Number Verification call.

Note that my option 2 is different in the sense that as soon as you see two sources of phone number information, you will always return an error code (and not only when there is a mismatch).

Option 3 is also different, because here you make it more explicit that a Number Verification is included, by provding an explict answer on the phone number in the request (just like how you respond with Number Verification).

[MarkCornall]

A valid point and a way of getting a free number verification. Although we are trying to be helpful surely the use of a more generic error rather than an invalid token indication would mean that you could then not rely on the result from any of these APIs and would need to call number verify for a real answer. I can see any of the other APIs as being more premium to number verify.

[AxelNennker]

For some definition of "premium"...
I expect that number verification is an attractive API for high-volume services that have billions of users, while sim-swap is an Account Take Over Protection or Risk Management API which is probably rarer.

Hard to say whether billions times small fee greater or less than millions time high fee.

[AxelNennker]

I think all APIs that have a device object or phoneNumber as a parameter should be aware that the API could be used to validate that information.

[HuubAppelboom]

@AxelNennker @MarkCornall There will be API's at a lower price point than Number Verify and at a higher price point. Either way you can have a revenue leak.

But what is more relevant I think is that you may have a privacy leak which the MNO or the API Consumer is not aware of.
Under GDPR, you will need to be transparent about what gets verified, and having a "hidden" verification in a protocol is not a good idea. Also, asking for personal information in a resource call when it is not needed is not a good idea, you should always try to minimize this.

[jpengar]

A valid point and a way of getting a free number verification. Although we are trying to be helpful surely the use of a more generic error rather than an invalid token indication would mean that you could then not rely on the result from any of these APIs and would need to call number verify for a real answer. I can see any of the other APIs as being more premium to number verify.

The issue is not solely the error message returned. The primary use case for Number Verification is to confirm a number "positively," under the assumption that the number is already known. It is not intended for discovering numbers through trial and error. When using the Sim Swap API or similar services as an alternative, the objective is to obtain a 200 status code to verify the number.

As long as CAMARA asserts that a 200 API response indicates successful validation of the number against the provided token, we are inherently disclosing this verification.

If an error occurs, it may be unclear whether it is due to a mismatch of the phone number or another issue. However, it can already be inferred that the number has not been verified.

[MarkCornall]

Are we also open to someone calling the authorisation flow and getting the information that they need but not finally calling the actual API?

[AxelNennker]

Are we also open to someone calling the authorisation flow and getting the information that they need but not finally calling the actual API?

That seems to be a question for Camara business people.
if e.g. the client pays a monthly fee for being registered and there is a maximum of created access-tokens per month, then we might not care much.

[eric-murray]

If it is agreed that this type of information leak is to be avoided, then I think the decision for Commonalities is whether providing a 3-legged access token and a device object in the service API call is always and error or never an error. It is only because we currently only give an error when the device identifiers do not match that we have an information leak.

So the options would be:

• Return an error if the API consumer provides both a 3-legged token and a device object (whether the device matches or not); or
• Ignore any device object provided if a 3-legged access token, and use the device identified by the token to fulfil the API request

As an API implementor, I slightly favour the second option (as, in fact, that is what Vodafone already do). But I understand that the API consumer may not be aware they are using a 3-legged token (maybe the developer got it from some library call) and could be misled by the response when they provided a device object that identifies a different device to the token.

So my preference is therefore that providing a 3-legged token and a device object should always be an error.

As to which error, I'd say a 422 still applies, but with a more generic code - maybe 422 UNNECESSARY_DEVICE_IDENTIFIER.

[HuubAppelboom]

@eric-murray

As to which error, I'd say a 422 still applies, but with a more generic code - maybe 422 UNNECESSARY_DEVICE_IDENTIFIER.

Aan alternative error code may be
400 - INVALID_ARGUMENT - Client specified an invalid argument, request body or query param

This already exsists, and it covers it (the phone number should not be in the request)

[eric-murray]

@HuubAppelboom

As to which error, I'd say a 422 still applies, but with a more generic code - maybe 422 UNNECESSARY_DEVICE_IDENTIFIER.

Aan alternative error code may be 400 - INVALID_ARGUMENT - Client specified an invalid argument, request body or query param

My instinct is to try to restrict 400 errors to clear violations of the API OAS definition (for example, pattern violations, or not including required parameters). The 400 error is a strong hint to the API consumer to read the API definition in more detail.

In this case, the Device object must remain optional in case a 2-legged token is provided, and if providing a (correctly formatted) optional parameter results in an error, I think more explanation is required. The reason for the error may not be obvious to the developer, particularly when the provided phone number does match that associated with the token, and certainly wouldn't be picked up by any additional OAS validation.

Now maybe this additional error documentation could be in the error message, but I think giving the error its own code would make it simpler for the developer to search for the correct documentation to explain their error.

[eric-murray]

I'd like to try and progress this issue as I think it is important and something that we should conclude before the Spring '25 meta-release.

My proposed solution is that:

• Providing an explicit device identifier when a 3-legged token is being used should ALWAYS be an error;
• The error code should be a new 422 code, such as 422 UNNECESSARY_DEVICE_IDENTIFIER

I think this is simple to implement, and provides a clear indication to the API consumer as to why their request failed.

Can we agree on that solution, or are there alternative solutions in play?

[HuubAppelboom]

@eric-murray This seems a simple proposal that can fix this issue, and prevent the misuse.

[ToshiWakayama-KDDI]

Hello all,

Sorry that I have not participated in this discussion due to work on Fall24 Meta, but now I have some comment.

Thank you, @eric-murray, for the proposal. In principle, it looks good, but wouldn't it be possible to add something like 'in principle' and to make room for sub projects to reshape it? Actually KnowYourCustomer SP is having discusion on this topic, because KYC Match API uses 'phoneNumber' (a device identifier, I understand) as an optional parameter even in 3-legged cases. So, from this perspective, for example, another phrase to add to Eric's proposal may be 'unless API specific requirements / use cases exist'.

I don't mean to reverse the past discussion, but I feel too much restriction and less flexibility may lead to narowing down potential new businesses and potential new use cases, which may not be good to the industry ecosystem.

Best regards,
Toshi

[eric-murray]

Hi @ToshiWakayama-KDDI

So this issue, and my proposal, only apply for APIs that can accept either a 2-legged or 3-legged access token. Such APIs must allow the API consumer to provide an optional device identifier to identify the "subject" of the API if a 2-legged token is used.

APIs such as KYC Match and Number Verification just do not work with 2-legged access tokens. As a 2-legged token is not an option, the purpose of the phoneNumber field is entirely different - the API is explicitly validating that identifier with that of the end user identified in the token.

So any proposal adopted by Commonalities for the API guidelines would be clear that it only applies to APIs that accept both 2-legged and 3-legged tokens.

As a sidenote, APIs such as KYC Match and Number Verification are still vulnerable to misuse if the token is obtained using the CIBA flow. Either the login_hint is the phone number, in which case verifying it against a phone number provided in the API call itself is pointless, or the login_hint is the current ip/port of the end user, in which case the API is allowing ip/port to MSISDN lookup, which is an abuse of the API.

So APIs such as KYC Match and Number Verification should not allow validation of the phone number if the 3-legged token is obtained using the CIBA flow.

[PedroDiez]

Within Commonalities, can we move forward with this baseline proposal?
#259 (comment)

[eric-murray]

Hi @PedroDiez
I'm happy to raise a PR for this.

However, I'd appreciate that if anyone has further comments or proposals, they raise them in this issue, rather than waiting until I have proposed a PR and opening up discussion there. Preparing a PR is a lot more work than debating a topic in the issue.

[bigludo7]

@eric-murray From Orange you have our support for:

My proposed solution is that:

Providing an explicit device identifier when a 3-legged token is being used should ALWAYS be an error;
The error code should be a new 422 code, such as 422 UNNECESSARY_DEVICE_IDENTIFIER

cc: @patrice-conil

[PedroDiez]

Hi @eric-murray, understood your point:

At least to be clear from my side:

• Agree with the baseline API misuse #259 (comment)
• I think better to have specific errors for device and phoneNumber:

422 UNNECESSARY_DEVICE_IDENTIFIER
422 UNNECESSARY_PHONE_NUMBER (There are APIs that not have the concept of device and the exception could be misleading)

• Agree "API guidelines would be clear that it only applies to APIs that accept both 2-legged and 3-legged tokens."

[PedroDiez]

And one doubt @eric-murray, not related to the "core" resolution of this issue. I would like to understand your view about KYC-Match do not work in a 2-legged scenario. I mean from the service point of view the API could work in a 2-legged scenario. Other thing is that from Business side would not be considered to be accessed in such a way due privacy reasons or any legal constraint.

[eric-murray]

@PedroDiez

I would like to understand your view about KYC-Match do not work in a 2-legged scenario

Maybe I'm misunderstanding the role of phoneNumber in this API, but the API documentation states:

The API supports a multi-level hierarchy of property validation. In addition to the initial verification of the phoneNumber, an additional idDocument validation may occur based on different Operator requirements. This means that, in those cases, if the value of idDocument is not provided or it does not match the one bound to the specific phone number in the Operator systems, the operation will return an error.

So how is the "verification of the phoneNumber" achieved without a 3-legged token? I had assumed the phoneNumber provided in the body was validated against the identity bound to the 3-legged token (in the same way as Number Verification, which also does not accept 2-legged tokens).

If the API accepts 2-legged access tokens, then the phoneNumber is not being "verified" at all. Rather it is being used as the definitive identifier against which all other data is being matched for that scenario. In which case this API is indeed subject to the potential misuse identified by @HuubAppelboom - the API consumer does not know the phoneNumber, gets a 3-legged token, explicitly specifies the phoneNumber they think the end user is using, and gets confirmation from the API as to whether or not that is true.

I had understood from @ToshiWakayama-KDDI that such misuse was not possible for KYC Match, which would only be true if the only purpose of phoneNumber was to be validated against the 3-legged token. If it does accept 2-legged tokens, then 3-legged token + explicit phoneNumber should be an error.

Unless phoneNumber has one contextual meaning when the access token is 3-legged (i.e. the "Number Verification" use case), and a different contextual meaning when the token is 2-legged (the "definitive end user identifier" meaning), in which case that really ought to be documented in more detail.

[eric-murray]

@PedroDiez

I think better to have specific errors for device and phoneNumber

I don't see the need to have parallel error codes for device and phoneNumber for what is, logically, exactly the same error.

I think this will result in a proliferation of error codes, and complicate generation and handling of such errors, just to avoid that an API consumer who thinks they are querying a "subscription" (or "account" or "identity" or whatever you want to call it) does not get confused by an error code using the term "DEVICE". Far better just to customise the message.

But I will raise that objection in more detail in #321.

[ToshiWakayama-KDDI]

Thank you, @eric-murray , @PedroDiez .

And one doubt @eric-murray, not related to the "core" resolution of this issue. I would like to understand your view about KYC-Match do not work in a 2-legged scenario. I mean from the service point of view the API could work in a 2-legged scenario. Other thing is that from Business side would not be considered to be accessed in such a way due privacy reasons or any legal constraint.

Actually, Pedro's this point was partly aligned with what I wanted to share by my prevous comment #259 (comment) . I always wonder why KYC Match is restricted for 3-legged access token scenarios, thinking it could work in 2-legged access token scenarios as well.

If the API accepts 2-legged access tokens, then the phoneNumber is not being "verified" at all. Rather it is being used as the definitive identifier against which all other data is being matched for that scenario. In which case this API is indeed subject to the potential misuse identified by @HuubAppelboom - the API consumer does not know the phoneNumber, gets a 3-legged token, explicitly specifies the phoneNumber they think the end user is using, and gets confirmation from the API as to whether or not that is true.

Considerint the above Eric's point, there could be the potential misuse, but from business perspective, it still could work. For example, if an API provider could provide phoneNumber match by KYC-Match, avoiding forcing API users to call two APIs.

Unless phoneNumber has one contextual meaning when the access token is 3-legged (i.e. the "Number Verification" use case), and a different contextual meaning when the token is 2-legged (the "definitive end user identifier" meaning), in which case that really ought to be documented in more detail.

This Eric's point is aligned with what I was thinking. I think phoneNumber in Number Verificaiton is not always the same as phoneNumber in KYC Match, and I think we can discuss KYC Match use cases for 3-legged access token as well as 2-legged access token furthre in KYC SP.

So, as we KYC-SP need some more time to discuss, I would like to recall my previous comment:

In principle, it looks good, but wouldn't it be possible to add something like 'in principle' and to make room for sub projects to reshape it? Actually KnowYourCustomer SP is having discusion on this topic, because KYC Match API uses 'phoneNumber' (a device identifier, I understand) as an optional parameter even in 3-legged cases. So, from this perspective, for example, another phrase to add to Eric's proposal may be 'unless API specific requirements / use cases exist'.

If other colleagues accept this kind of exception.

Best regards,
Toshi

[eric-murray]

@ToshiWakayama-KDDI @PedroDiez
Well, certainly one way around the "API misuse" problem is to declare that it is actually intended that the API provide the "Number Verification" functionality when both a 3-legged token and explicit phoneNumber (or device object) is provided by the API consumer.

As it is also intended that KYC-Match accept 2-legged access tokens, a simple "this rule only applies to APIs that accept both 3-legged and 2-legged" is no longer sufficient, as that would exempt Number Verification from this new rule, but not KYC-Match nor any other API that wants to also offer "Number Verification" functionality in addition to its primary purpose.

How about something like:
"For an API call where the API consumer provides both a 3-legged access token and an explicit end user identifier (e.g. phoneNumber or a device object), a 422 UNNECESSARY_DEVICE_IDENTIFIER (*) error MUST be returned UNLESS the scope of the API requires it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token"

(*) Working title. We could consider a more "universal" error, such as UNNECESSARY_DEVICE_OR_SUBSCRIPTION_IDENTIFIER, UNNECESSARY_END_USER_IDENTIFIER or even just UNNECCESSARY_IDENTIFIER and give the name of the identifier in the message.

[PedroDiez]

Hi @eric-murray,

Regarding KYC-Match, thanks for your view.

From our business view it could also work in 2-legged (trusting in the phoneNumber indicated and using it as the reference for the backend logic). Other point is whether Business may want to expose in such a way or not. Anyway, it is a matter for KYC WG discussions.

[PedroDiez]

@ToshiWakayama-KDDI @PedroDiez Well, certainly one way around the "API misuse" problem is to declare that it is actually intended that the API provide the "Number Verification" functionality when both a 3-legged token and explicit phoneNumber (or device object) is provided by the API consumer.

As it is also intended that KYC-Match accept 2-legged access tokens, a simple "this rule only applies to APIs that accept both 3-legged and 2-legged" is no longer sufficient, as that would exempt Number Verification from this new rule, but not KYC-Match nor any other API that wants to also offer "Number Verification" functionality in addition to its primary purpose.

How about something like: "For an API call where the API consumer provides both a 3-legged access token and an explicit end user identifier (e.g. phoneNumber or a device object), a 422 UNNECESSARY_DEVICE_IDENTIFIER (*) error MUST be returned UNLESS the scope of the API requires it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token"

(*) Working title. We could consider a more "universal" error, such as UNNECESSARY_DEVICE_OR_SUBSCRIPTION_IDENTIFIER, UNNECESSARY_END_USER_IDENTIFIER or even just UNNECCESSARY_IDENTIFIER and give the name of the identifier in the message.

Hi @eric-murray, @ToshiWakayama-KDDI,

I think the approach can work, Agree Eric is the same error condition but referred to the concept of device or phoneNumber. I wanted to be precise in that way. I understand the concern you raise of duplicating errors even I think would not be so much.

I think we can move forward with the proposal (not attached to device nor phoneNumber in the terms of the code, as more information can be provided within message`):

For an API call where the API consumer provides both a 3-legged access token and an explicit end user identifier (e.g. `phoneNumber` or a `device` object), a `422 UNNECESSARY_IDENTIFIER` error MUST be returned UNLESS the scope of the API requires it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token

[PedroDiez]

Based on that, I will reformulate some basis under the Issue #321

[eric-murray]

Anyway, it is a matter for KYC WG discussions.

Agree. I think I understand how that API is intended to work now, but this "dual use" of phoneNumber dependent on access token type really does need to be better documented.

I think we can move forward with the proposal

@jlurien made a proposal to simply adopt the term "IDENTIFIER" to cover both cases, which I'm happy with. I'm working on a PR for this issue, so will adopt that terminology for now. It can be revised before any merging once agreement is reached on the specific error codes.

[ToshiWakayama-KDDI]

Hi @eric-murray , @PedroDiez ,

As it is also intended that KYC-Match accept 2-legged access tokens, a simple "this rule only applies to APIs that accept both 3-legged and 2-legged" is no longer sufficient, as that would exempt Number Verification from this new rule, but not KYC-Match nor any other API that wants to also offer "Number Verification" functionality in addition to its primary purpose.

How about something like:
"For an API call where the API consumer provides both a 3-legged access token and an explicit end user identifier (e.g. phoneNumber or a device object), a 422 UNNECESSARY_DEVICE_IDENTIFIER (*) error MUST be returned UNLESS the scope of the API requires it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token"

Sorry for the late response. I think the approach can work, as well, and I am happy with the above proposal. Thank you so much, Eric.

Anyway, it is a matter for KYC WG discussions.

Thank you also for your valuable opinions on KYC-Match 2-legged case. We will continue discussion in KYC SP, taking your views into account.

Best regards,
Toshi
KDDI