Problem description
The 422 IDENTIFIER_MISMATCH error code is returned when:

• a 2-legged access token is used, and hence the device is identified by an explicit device object following the Device schema; and
• the device property contains multiple device identifiers; and
• the supplied device identifiers identify different devices

If multiple device identifiers are provided, and these all identify the same device, then no error is returned

The problem with this approach is that it allows the API consumer to correlate different device identifiers, particularly phoneNumber (i.e. MSISDN) and IP address. This would allow functionality similar to Number Verification when the API consumer knows the IP address / port of the device and the MSISDN registered by the end user.

Possible evolution
This was discussed in Issue #295.

The proposed solution is:

• the API consumer can continue to specify multiple device identifiers when a 2-legged access token is used
• a given API provider will use only a single identifier to identify the device
• the single device identifier used by the API provider will be included in the API response
• remove the IDENTIFIER_MISMATCH error from the API design guidelines

For example:

POST /endpoint
{
  "device": { "phoneNumber": "+1234567890", "ipv4Address": { "publicAddress": "1.2.3.4", "publicPort": "10000" } }
}

Response:

200
Content-Type: application/json
{
  "device": { "phoneNumber": "+1234567890" },
  "informationActuallyWanted": true
}

Including the device parameter would be mandatory for 2-legged access tokens, but would not be included for 3-legged access tokens.

The advantages of this proposal are:

• It is not a breaking change, as it only requires an additional option response parameter for those APIs that do not already have it
• It continues to allow API consumers to specify multiple device identifiers, which will increase inter-operability in the case that API providers support a different subset of the available device identifiers
• No information is returned to the API consumer that they do not already know

Alternative solution
The alternative is to only allow a single device identifier to be specified in the device object:

    Device:
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        networkAccessIdentifier:
          $ref: "#/components/schemas/NetworkAccessIdentifier"
        ipv4Address:
          $ref: "#/components/schemas/DeviceIpv4Addr"
        ipv6Address:
          $ref: "#/components/schemas/DeviceIpv6Address"
      minProperties: 1
      maxProperties: 1

The API Provider would return UNSUPPORTED_IDENTIFIER if they did not support that identifier, and the API consumer could then try again with a different device identifier.

The disadvantages of this approach are:

• it is a breaking change, as device objects that included multiple identifiers for the same device would now be rejected
• it complicates inter-operability as, for a given device object format, some API providers may accept it whereas others will return 422 UNSUPPORTED_IDENTIFIER
• it would require the API consumer to learn to try a different device identifier in response to a 422 UNSUPPORTED_IDENTIFIER error

Additional context
None