use scopes and introduce a pairwise pseudonymous identifer

code/API_definitions/device-identifier.yaml

@@ -5,8 +5,9 @@ info:
   description: |
     # Summary
 
-    The Mobile Device Identifier API returns details of the physical mobile device currently being used by a specified mobile subscriber. The following information can be returned:
-     - A unique network identifier for the specific device itself (IMEI SV and IMEI)
+    The Mobile Device Identifier API returns details of the physical mobile device currently being used by a specified mobile subscriber.
+    The following information can be returned:
+     - A unique network identifier for the specific device itself (IMEI SV or IMEI or PPID)
      - A network identifier for the device make and model (IMEI Type Allocation Code)
      - Device manufacturer name and model
 
@@ -24,14 +25,17 @@ info:
     - The following 6 digits are the serial number of the device for that TAC
     - For IMEI, the remaining digit is a check digit
     - For IMEI SV, the remaining two digits are the software version
+    The IMEI and IMEISV are global permanent identifiers which can be used for user tracking.
+
+    The PPID is a pairwise pseudonymous identifier, which is often derived from IMEI or IMEISV but it can also be a randomly generated database entry. The [OpenId Connect standard](https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg) discusses several algorithms to compute a PPID.
 
     TACs are issued and managed by the GSMA, and can be queried using the [GSMA IMEI database](https://www.gsma.com/aboutus/workinggroups/terminal-steering-group/imei-database).
 
     The mobile network associates this device identifier with the mobile subscription currently using the device. The mobile subscription is defined by the Subscriber Identity Module (SIM) currently active in the mobile device. This may be a removable SIM or an eSIM. In either case, it is possible for the association between the device identifier and subscription to change - for example, when a physical SIM is transferred to another mobile device.
 
     ![Device Identifier API Overview](https://raw.githubusercontent.com/camaraproject/DeviceIdentifier/main/documentation/API_documentation/resources/Device_Identifier_Overview.png)
 
-    The Device Identifier API allows the API consumer to obtain the IMEI and associated parameters for a specified mobile subscription identifier or equivalent. The mobile subscription can be identified using one of the following subscription identifiers:
+    The Device Identifier API allows the API consumer to obtain a device identifer and associated parameters for a specified mobile subscription identifier or equivalent. The mobile subscription can be identified using one of the following subscription identifiers:
     - the subscription phone number (also known as MSISDN)
     - the subscription network access identifier, which is a domain specific identifier typically allocated to devices that do not require voice / SMS connectivity
     - the current IP address and port alloacted to the device, which must be an IPv6 or public IPv4 address
@@ -151,7 +155,17 @@ paths:
         - Get Device Identifiers
       security:
         - openId:
-            - device-identifier:retrieve-identifier
+            - device-identifier:retrieve-identifier-imei
+        - openId:
+            - device-identifier:retrieve-identifier-imeisv
+        - openId:
+            - device-identifier:retrieve-identifier-ppid
+        - openId:
+            - device-identifier:retrieve-identifier-tac
+        - openId:
+            - device-identifier:retrieve-identifier-model
+        - openId:
+            - device-identifier:retrieve-identifier-manufacturer
 
       parameters:
         - in: header
@@ -272,7 +286,6 @@ components:
           schema:
             required:
               - lastChecked
-              - imei
             allOf:
               - $ref: "#/components/schemas/LastChecked"
               - $ref: "#/components/schemas/DeviceIdentifier"
@@ -547,6 +560,10 @@ components:
           type: string
           description: IMEI of the device
           example: "4901542032375181"
+        ppid:
+          type: string
+          description: a pairwise pseudonymous identifier
+          example: "b083f65ccdad365d7489fff24b6d5074b30c12b6d81db3404d25964ffd908813"
 
     DeviceType:
       description: |