Clarification on Phone Number from access token

[FabrizioMoggio]

Considering https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#appendix-a-infodescription-template-for-device-identification-from-access-token

and especially:

Validation mechanism:

• The server will extract the device identification from the access token, IF AVAILABLE.

My understanding is that, in a 3 legged scenario, the Phone Number CAN be:

• just in the access token
• just in "Device" or in any other parameter defined by the API
• in both (in this case they must be equal)

Is my understanding correct?

[PedroDiez]

"just in "Device" or in any other parameter defined by the API", this would the case for instance of 2-legged scenario. Indicated in the documentation but just Fabrizio to have certainty on that

[FabrizioMoggio]

just to explain.

I thought that in a 3-legged scenario the access token always provides the phone number.

Then I started writing the gherkin test cases considering the error codes and we have:

• If the device object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 UNIDENTIFIABLE_DEVICE error

About 422: if we get that message it means a VALID access token (with no info about the phone number) is used by the API Consumer. Otherwise the API Consumer couldn't have reached the API endpoint.

422 plus the sentence in the documentation: "The server will extract the device identification from the access token, IF AVAILABLE" led me to open this Discussion.

[PedroDiez]

In 3-legged scenario, guideline is "When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request", so yes in 3-legged scenario the access token provides it.

[bigludo7]

Hello

@FabrizioMoggio If the device object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 UNIDENTIFIABLE_DEVICE error

My understanding of the guidelines is to have a 404 here with DEVICE_NOT_FOUND but in the appendix this is 422 and UNIDENTIFIABLE_DEVICE error.
You're probably right Fabrizio with 422 but we need a guidelines update?

[FabrizioMoggio]

My understanding so far, from the discussion:

1. with 3-legs the access token always provides the phone number
2. it can happen that the API Consumer is allowed to invoke the endpoint by the Auth/Consent system but the phone number in the access token is not good for the API Provider. And consequently 422 is returned.

number 2) happens for an error by the API Consumer.

[FabrizioMoggio]

Hello

@FabrizioMoggio If the device object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 UNIDENTIFIABLE_DEVICE error

My understanding of the guidelines is to have a 404 here with DEVICE_NOT_FOUND but in the appendix this is 422 and UNIDENTIFIABLE_DEVICE error. You're probably right Fabrizio with 422 but we need a guidelines update?

To include 422, an update here is required: https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#32-http-response-codes