Clarification required on 403 INVALID_TOKEN_CONTEXT vs 422 UNNECESSARY_IDENTIFIER

[bigludo7]

Problem description
I should confess that I'm a bit confuse about the use 403 INVALID_TOKEN_CONTEXT vs 422 UNNECESSARY_IDENTIFIER in the context of 3-legs access token.

Are we supposed to use below set 1 or 2?

Set 1:
Rule 1: If in the access token the device identifier is A and in the body we have B then we throw back 403 INVALID_TOKEN_CONTEXT
Rule2 : If in the access token the device identifier is A and in the body we have A then we throw back 422 UNNECESSARY_IDENTIFIER

Set2:
When I'm reading our design document I can also understand
Rule 1: If in the access token the device identifier is A and in the body we have B then we throw back 422 UNNECESSARY_IDENTIFIER
Rule2 : If in the access token the device identifier is A and in the body we have A then we throw back 422 UNNECESSARY_IDENTIFIER

Expected action

Additional context

[eric-murray]

Hi @bigludo7

In fact, both sets of rules are being used.

For APIs which DO NOT allow the API consumer to receive confirmation as to whether their phone number matches that explicitly provided in the request body, then Set2 applies - a 422 UNNECESSARY_IDENTIFIER is always returned. This should be most APIs.

But for APIs that DO allow this and have obtained the necessary consent from the user, then Set1 should be used. The only example I know is KYC Match, which allows the phone number to be explicitly provided in the request body even when the access token is 3-legged, and returns 403 INVALID_TOKEN_CONTEXT if the identities do not match.

There may be other APIs in this second category - each API team needs to have a think as to whether such functionality is part of their use case. All APIs that do not require this functionality should remove the 403 INVALID_TOKEN_CONTEXT error if they still have it in the YAML.

Number Verification does not require to use either rule set, of course, because whether the identities match or not is returned in the 200 OK response JSON, and is not an error.

[bigludo7]

Thanks a lot @eric-murray - make a lot of sense.

[sachinvodafone]

Hi @bigludo7

In fact, both sets of rules are being used.

For APIs which DO NOT allow the API consumer to receive confirmation as to whether their phone number matches that explicitly provided in the request body, then Set2 applies - a 422 UNNECESSARY_IDENTIFIER is always returned. This should be most APIs.

But for APIs that DO allow this and have obtained the necessary consent from the user, then Set1 should be used. The only example I know is KYC Match, which allows the phone number to be explicitly provided in the request body even when the access token is 3-legged, and returns 403 INVALID_TOKEN_CONTEXT if the identities do not match.

There may be other APIs in this second category - each API team needs to have a think as to whether such functionality is part of their use case. All APIs that do not require this functionality should remove the 403 INVALID_TOKEN_CONTEXT error if they still have it in the YAML.

Number Verification does not require to use either rule set, of course, because whether the identities match or not is returned in the 200 OK response JSON, and is not an error.

Hi @eric-murray , Does it depend on the provider whether 422 UNNECESSARY_IDENTIFIER is considered during validation, or is it a standard requirement across all API specifications? As I see it, it would make more sense to use the identifier in the access token as the primary source for processing, especially for APIs that don’t confirm whether the phone number in the request body matches the one in the token. In such cases, any additional identifiers in the body should be treated as redundant and ignored, instead of returning a 422 UNNECESSARY_IDENTIFIER.

[eric-murray]

Hi @sachinvodafone

That second option of just ignoring any explicit identifier provided along with a 3-legged access token was one of the two options discussed in Issue #259. The problem with that approach is that the API consumer may not know they are using a 3-legged token, and thus the API may be silently fulfilled for a different user to the one they intended without them realising.

So it is far safer to throw an error and get the API consumer to fix their request.

[PedroDiez]

Hi,

@bigludo7 Eric's comment, reflects current commonalities information.

I think unique API so far that may apply set 1 would be KYC match.

The purpose of #259 was adding the UNNECESSARY_IDENTIFIER error is so that the APIs do not provide implicit Number Verification functionality, so this is the error to use in 3-legs if you do not want to provide that.

Our business is somehow worried with the case of KYC Match, as the purpose of Issue #259 was to avoid any API misuse as number verification functionality. That is something that will be managed and talked within KYC Match WG

[bigludo7]

Hello
Probably to close on this one we can add additional information in the table here

We have:

403	INVALID_TOKEN_CONTEXT	{{field}} is not consistent with access token.	Reflect some inconsistency between information in some field of the API and the related OAuth2 Token

Proposal:

403	INVALID_TOKEN_CONTEXT	{{field}} is not consistent with access token.	Reflect some inconsistency between information in some field of the API and the related OAuth2 Token. This error should be used only when the API requires that the API consumer receives confirmation as to whether their phone number matches that explicitly provided in the request body.

Make sense?

@rartych : happy to trigger a PR to close on this one.

[rartych]

@bigludo7 Thanks for the proposed resolution.

Is this sentence based on Appendix A text is clear enough?

(...) This error should be used only when the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the Three-Legged Access Token.

Feel free to modify it or keep your proposal in the PR.

@eric-murray Do you see the need to extend Appendix A with the guideline for 403 INVALID_TOKEN_CONTEXT usage?

[bigludo7]

@rartych Yes I will use your sentence.
I will make a PR to improve the table.

[eric-murray]

@rartych

Yes, an update would help. Currently we have:

In this case, a 422 UNNECESSARY_IDENTIFIER error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the Three-Legged Access Token.

I'd suggest to update this to:

• If the API scope DOES NOT allow explicit confirmation as to whether the identifiers match, a 422 UNNECESSARY_IDENTIFIER error MUST be returned whether the identifiers match or not
• If the API scope DOES allow explicit confirmation as to whether the identifiers match, a 403 INVALID_TOKEN_CONTEXT error MUST be returned if the identifiers do not match and the mismatch is not indicated using some other mechanism (e.g. as an explicit field in the API response body)