device-identifier.yaml

openapi: 3.0.3
info:
  title: Device Identifier
  version: wip
  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)
     - A pseudonymised network identifier for the specific device itself (Pairwise Pseudonymous Identifier)
     - A network identifier for the device make and model (IMEI Type Allocation Code)
     - Device manufacturer name and model

     This information can be useful in a number of scenarios, such as the following:
     - For insurance purposes, to automatically identify a device that a customer wishes to insure
     - For security / fraud reasons, to establish that a customer is not using a device they claim to have broken or lost
     - For service delivery reasons, to optimise content for a particular device or OS type

    # Introduction

    Mobile devices are allocated a unique identifier by the manufacturer, known as the International Mobile Equipment Identity, or IMEI. The current software version (SV) of the device can be appended to this, in which case the identifier is known as the IMEI SV. This identifier is signalled to the mobile network when the device connects, both to confirm that the device is not blocked, and also allow device dependent network configurations to be implemented.

    The IMEI is a 15 digit integer, and the IMEI SV is a 16 digit integer:
    - The first 8 digits are known as the Type Allocation Code (TAC), and identify the manufacturer and model of the device
    - 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

    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 or more 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

    The API can be called by an API consumer to establish an identifier for the physical device currently being used by the mobile subscription. The information returned will depend upon the consent that the end user (i.e. mobile subscription owner) has given for that information to be provided to the API consumer. For example, if the end user has not consented to any information about their device being given, then the API consumer will receive an error in response to their request. Otherwise, the information that the end user has consented to being given will be returned.

    # Relevant terms and definitions

    ### Device Identifier API service endpoint
    The URL pointing to the RESTful resource of the Device Identifier API.

    ### Identifier for the mobile subscription
    At least one identifier for the mobile subscription from the following four options:
      - Phone number (i.e. MSISDN)
      - Network Access Identifier assigned by the mobile network operator for the device
      - IPv6 address
      - IPv4 address

    ### Identifier for the physical mobile device
    The IMEI or IMEISV of the physical mobile device

    ### Pairwise Pseudonymous Identifier
    An identifier that has been pseudonymised such that the resulting pseudonymous identifier is unique to but persistent for a given API consumer

    # API functionality

    The API defines three service endpoints:

    - `POST /retrieve-identifier` to get details about the specific device being used by a given mobile subscriber, including IMEI / IMEISV and the type of device
    - `POST /retrieve-type` to get details only about the type (i.e. manufacturer and model) of device being used by a given mobile subscriber
    - `POST /retrieve-ppid` to get a pseudonymised identifier for the specific device being used by a given mobile subscriber

    To call any of these endpoints, the API consumer must first obtain a valid access token from the token endpoint, which is then passed as an Authorization header. When a 2-legged access token is used, the API consumer must also pass at least one of the available mobile subscription identifiers in the body of the request.

    If the request is valid, the API response is a JSON object containing the data that the end user has consented to sharing with the API consumer.
    - When calling endpoint `retrieve-identifier`, the response will always contain `imei`
    - When calling endpoint `retrieve-type`, the response will always contain `tac`
    - When calling endpoint `retrieve-ppid`, the response will always contain `ppid`
    - Responses will also always contain a `lastChecked` field, indicating when the information provided was last confirmed to be correct
    - Other response parameters are implementation dependent, and thus optional

    An example of a JSON response object is as follows:
    ```
    {
       "lastChecked": "2024-02-20T10:41:38.657Z",
       "imeisv": "49015420323751800",
       "imei": "4901542032375181",
       "tac": "49015420",
       "model": "3110",
       "manufacturer": "Nokia"
    }
    ```

    ## Error handling

    Errors may be returned for the following reasons. Note that this list is not exhaustive.

    `401 UNAUTHENTICATED`:
    - The access token is not a valid access token for the API provider
    - The access token was valid but has now expired

    `400 INVALID_ARGUMENT`:
    - The API request is not compliant with this OAS definition

    `400 OUT_OF_RANGE`:
    - A parameter value in the API request is outwith the range documented in this OAS definition for that parameter

    `404 IDENTIFIER_NOT_FOUND`:
    - The device identified by the `device` object in the request is not managed by the API provider

    `403 PERMISSION_DENIED`:
    - The access token does not have the required scope for the endpoint being called
    - The end user has not consented to the API consumer getting access to the device identifier information (2-legged access token only)

    `422 SERVICE_NOT_APPLICABLE`:
    - A device identifier cannot be provided for the identified device. For example, the phone number might identify a landline.

    `422 UNSUPPORTED_IDENTIFIER`:
    - A parameter provided in the `device` object is not supported by this implementation (e.g. `networkAccessIdentifier`)

    `422 MISSING_IDENTIFIER`:
    `422 UNNECESSARY_IDENTIFIER`:
    - See the section "Identifying the device from the access token" below

    `429 QUOTA_EXCEEDED`:
    - The API consumer has used up the quota of API requests that they were allocated for this API

    `429 TOO_MANY_REQUESTS`:
    - The rate at which the API consumer is sending requests has exceeded that allowed by the API provider. Try again later.

    ### Additional CAMARA error responses

    The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.

    Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.

    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.

    # Further info and support

    ## Authorization and authentication

    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.

    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.

    In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.

    ## Identifying the device from the access token

    This API requires the API consumer to identify a device as the subject of the API as follows:
    - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.

    - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.

    This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process.

    ### Error handling:
    - If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.

    - If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.

    ## Multi-SIM scenario handling

    In scenarios where a main phone number is shared between multiple devices, each of which has its own individual "secondary" phone number (e.g. connectivity plans that let you share your airtime and data allowances with a smartwatch or eSIM-enabled tablet), the phone number passed by the API consumer will be treated as the secondary phone number, and hence the identifier returned will be that of the single device associated with that phone number (e.g. smartphone, smartwatch, or eSIM-enabled tablet).

    In such scenarios, the "primary" device is usually allocated the same main and secondary phone numbers, and hence providing the main phone number to the API will return the identity of the primary device (usually the smartphone) and not any associated devices.

    (FAQs will be added in a later version of the documentation)

  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-camara-commonalities: 0.6

externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/DeviceIdentifier

servers:
  - url: "{apiRoot}/device-identifier/vwip"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`

tags:
  - name: Get Device Identifiers
    description: Retrieve details about the device being used by a mobile subscriber

paths:
  "/retrieve-identifier":
    post:
      summary: Get details about the specific device being used by a given mobile subscriber
      description: Get details about the specific device being used by a given mobile subscriber
      operationId: retrieveIdentifier
      tags:
        - Get Device Identifiers
      security:
        - openId:
            - device-identifier:retrieve-identifier
      parameters:
        - $ref: "#/components/parameters/x-correlator"

      requestBody:
        description: Parameters to create a new session
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestBody"
            examples:
              Identify Device By 3-Legged Access Token:
                $ref: '#/components/examples/IdentifyDeviceBy3LeggedToken'
              Identify Device By Phone Number:
                $ref: '#/components/examples/IdentifyDeviceByPhoneNumber'
              Identify Device By IP Address:
                $ref: '#/components/examples/IdentifyDeviceByIPAddress'
              Identify Device By Multiple Identifiers:
                $ref: '#/components/examples/IdentifyDeviceByMultipleIdentifiers'

      responses:
        "200":
          $ref: '#/components/responses/200RetrieveIdentifier'
        "400":
          $ref: '#/components/responses/400BadRequest'
        "401":
          $ref: '#/components/responses/401Unauthorized'
        "403":
          $ref: '#/components/responses/403Forbidden'
        "404":
          $ref: '#/components/responses/404NotFound'
        "422":
          $ref: '#/components/responses/422UnprocessableContent'
        "429":
          $ref: '#/components/responses/429TooManyRequests'

  "/retrieve-type":
    post:
      summary: Get details about the type of device being used by a given mobile subscriber
      description: Get details about the type of device being used by a given mobile subscriber
      operationId: retrieveType
      tags:
        - Get Device Identifiers
      security:
        - openId:
            - device-identifier:retrieve-type
      parameters:
        - $ref: "#/components/parameters/x-correlator"

      requestBody:
        description: Parameters to create a new session
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestBody"
            examples:
              Identify Device By 3-Legged Access Token:
                $ref: '#/components/examples/IdentifyDeviceBy3LeggedToken'
              Identify Device By Phone Number:
                $ref: '#/components/examples/IdentifyDeviceByPhoneNumber'
              Identify Device By IP Address:
                $ref: '#/components/examples/IdentifyDeviceByIPAddress'
              Identify Device By Multiple Identifiers:
                $ref: '#/components/examples/IdentifyDeviceByMultipleIdentifiers'

      responses:
        "200":
          $ref: '#/components/responses/200RetrieveType'
        "400":
          $ref: '#/components/responses/400BadRequest'
        "401":
          $ref: '#/components/responses/401Unauthorized'
        "403":
          $ref: '#/components/responses/403Forbidden'
        "404":
          $ref: '#/components/responses/404NotFound'
        "422":
          $ref: '#/components/responses/422UnprocessableContent'
        "429":
          $ref: '#/components/responses/429TooManyRequests'

  "/retrieve-ppid":
    post:
      summary: Get a pseudonymous identifier for device being used by a given mobile subscriber
      description: Get a pseudonymous identifier for device being used by a given mobile subscriber
      operationId: retrievePPID
      tags:
        - Get Device Identifiers
      security:
        - openId:
            - device-identifier:retrieve-ppid
      parameters:
        - $ref: "#/components/parameters/x-correlator"

      requestBody:
        description: Parameters to identify the mobile subscription when a 2-legged access token is being used
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestBody"
            examples:
              Identify Device By 3-Legged Access Token:
                $ref: '#/components/examples/IdentifyDeviceBy3LeggedToken'
              Identify Device By Phone Number:
                $ref: '#/components/examples/IdentifyDeviceByPhoneNumber'
              Identify Device By IP Address:
                $ref: '#/components/examples/IdentifyDeviceByIPAddress'
              Identify Device By Multiple Identifiers:
                $ref: '#/components/examples/IdentifyDeviceByMultipleIdentifiers'

      responses:
        "200":
          $ref: '#/components/responses/200RetrievePPID'
        "400":
          $ref: '#/components/responses/400BadRequest'
        "401":
          $ref: '#/components/responses/401Unauthorized'
        "403":
          $ref: '#/components/responses/403Forbidden'
        "404":
          $ref: '#/components/responses/404NotFound'
        "422":
          $ref: '#/components/responses/422UnprocessableContent'
        "429":
          $ref: '#/components/responses/429TooManyRequests'

components:
  securitySchemes:
    openId:
      description: Common security scheme for all CAMARA APIs
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"

  headers:
    X-Correlator:
      description: Correlation id for the different services
      required: false
      schema:
        $ref: "#/components/schemas/XCorrelator"

  responses:
    200RetrieveIdentifier:
      description: An device identifier has been found for the specified subscriber
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            required:
              - lastChecked
              - imei
            allOf:
              - $ref: "#/components/schemas/CommonResponseBody"
              - $ref: "#/components/schemas/DeviceIdentifier"
              - $ref: "#/components/schemas/DeviceType"
          examples:
            Successful Identifier Retrieval:
              description: Device identifier has been successfully retrieved when the device subscription was identified by a 3-legged access token or single device subscription identifier
              value:
                lastChecked: "2024-02-20T10:41:38.657Z"
                imeisv: "49015420323751800"
                imei: "4901542032375181"
                tac: "49015420"
                model: "3110"
                manufacturer: "Nokia"
            Successful Identifier Retrieval With Device Disambiguation:
              description: Device identifier has been successfully retrieved when a 2-legged access token and multiple device subscription identifiers were provided
              value:
                device:
                  phoneNumber: "+123456789"
                lastChecked: "2024-02-20T10:41:38.657Z"
                imeisv: "49015420323751800"
                imei: "4901542032375181"
                tac: "49015420"
                model: "3110"
                manufacturer: "Nokia"

    200RetrieveType:
      description: A device identifier has been found for the specified subscriber
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            required:
              - lastChecked
              - tac
            allOf:
              - $ref: "#/components/schemas/CommonResponseBody"
              - $ref: "#/components/schemas/DeviceType"
          examples:
            Successful Type Retrieval:
              description: Device type has been successfully retrieved when the device subcsription was identified by a 3-legged access token or single device subscription identifier
              value:
                lastChecked: "2024-02-20T10:41:38.657Z"
                tac: "49015420"
                model: "3110"
                manufacturer: "Nokia"
            Successful Type Retrieval With Device Disambiguation:
              description: Device type has been successfully retrieved when a 2-legged access token and multiple device subscription identifiers were provided
              value:
                device:
                  phoneNumber: "+123456789"
                lastChecked: "2024-02-20T10:41:38.657Z"
                tac: "49015420"
                model: "3110"
                manufacturer: "Nokia"

    200RetrievePPID:
      description: A pseudonymous device identifier has been found for the specified mobile subscriber
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            required:
              - lastChecked
              - ppid
            allOf:
              - $ref: "#/components/schemas/CommonResponseBody"
              - $ref: "#/components/schemas/DevicePPID"
          examples:
            Successful PPID Retrieval:
              description: Device PPID has been successfully retrieved when the device subcsription was identified by a 3-legged access token or single device subscription identifier
              value:
                lastChecked: "2024-02-20T10:41:38.657Z"
                ppid: "b083f65ccdad365d7489fff24b6d5074b30c12b6d81db3404d25964ffd908813"
            Successful PPID Retrieval With Device Disambiguation:
              description: Device PPID has been successfully retrieved when a 2-legged access token and multiple device subscription identifiers were provided
              value:
                device:
                  phoneNumber: "+123456789"
                lastChecked: "2024-02-20T10:41:38.657Z"
                ppid: "b083f65ccdad365d7489fff24b6d5074b30c12b6d81db3404d25964ffd908813"

    400BadRequest:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
          examples:
            Insufficient Parameters:
              description: Sufficient parameters must be provided to allow the target UE to be identified
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "At least one of phoneNumber, networkAccessIdentifier, ipv4Address and ipv6Address must be specified"
            Inconsistent Device Properties:
              description: Device parameters provided identify different devices
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Multiple inconsistent device parameters specified"
            Invalid Network Access Identifier:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid format: networkAccessIdentifier"
            Invalid Phone Number:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid format: phoneNumber"
            Invalid IPv4 Address:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid format: ipv4Address"
            Invalid IPv6 Address:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid format: ipv6Address"
            Invalid Port Value:
              value:
                status: 400
                code: OUT_OF_RANGE
                message: "Invalid value: ipv4Address.publicPort"

    401Unauthorized:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 401
                  code:
                    enum:
                      - UNAUTHENTICATED
          examples:
            Unauthenticated Request:
              description: Request cannot be authenticated and a new authentication is required
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.

    403Forbidden:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 403
                  code:
                    enum:
                      - PERMISSION_DENIED
          examples:
            Permision Denied:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.

    404NotFound:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - IDENTIFIER_NOT_FOUND
          examples:
            Device Cannot Be Found:
              description: The provided identifier cannot be matched to a device known to the API provider
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: The provided identifier cannot be matched to a device.

    422UnprocessableContent:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 422
                  code:
                    enum:
                      - SERVICE_NOT_APPLICABLE
                      - MISSING_IDENTIFIER
                      - UNSUPPORTED_IDENTIFIER
                      - UNNECESSARY_IDENTIFIER
          examples:
            Service Not Applicable For Device:
              description: The service is not applicable for the identified device
              value:
                status: 422
                code: SERVICE_NOT_APPLICABLE
                message: The service is not applicable for the identified device.
            Unsupported Identifier:
              description: None of the provided identifiers is supported by the implementation
              value:
                status: 422
                code: UNSUPPORTED_IDENTIFIER
                message: None of the provided identifiers is supported by the implementation.
            Unnecessary Identifier:
              description: An explicit identifier has been provided for the device when this is already identified by the access token
              value:
                status: 422
                code: UNNECESSARY_IDENTIFIER
                message: An explicit identifier has been provided for the device when this is already identified by the access token
            Missing Identifier:
              description: An identifier is not included in the request and the device cannot be identified from the 2-legged access token
              value:
                status: 422
                code: MISSING_IDENTIFIER
                message: An identifier is not included in the request and the device cannot be identified from the 2-legged access token

    429TooManyRequests:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 429
                  code:
                    enum:
                      - QUOTA_EXCEEDED
                      - TOO_MANY_REQUESTS
          examples:
            Too Many Requests:
              description: Access to the API has been temporarily blocked due to quota or spike arrest limits being reached
              value:
                status: 429
                code: TOO_MANY_REQUESTS
                message: Rate limit reached
            Quota Exceeded:
              description: Request is rejected due to exceeding a business quota limit
              value:
                status: 429
                code: QUOTA_EXCEEDED
                message: Out of resource quota

  schemas:
    CommonResponseBody:
      description: |
        Common parameters to be included in all responses
      properties:
        device:
          description: The device subscription identifier that was used to identify the device whose identifier is being returned. If this property is not present, then the device subscription identifier specified in the request was used.
          allOf:
            - $ref: "#/components/schemas/DeviceResponse"
            - example: {"phoneNumber": "+123456789"}
        lastChecked:
          description: |
            Date and time that the information was last confirmed by the mobile operator to be correct. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
          type: string
          format: date-time
          example: "2024-02-20T10:41:38.657Z"

    DeviceIdentifier:
      description: |
        The individual physical mobile device identifier, as expressed by the IMEI and IMEISV
      type: object
      properties:
        imeisv:
          type: string
          description: IMEISV of the device
          example: "49015420323751800"
        imei:
          type: string
          description: IMEI of the device
          example: "4901542032375181"

    DeviceType:
      description: |
        The physical device type, as expressed by Type Approval Code, manufacturer name and model name
      type: object
      properties:
        tac:
          type: string
          description: IMEI TAC of the device
          example: "49015420"
        model:
          type: string
          description: Model of the device
          example: "3110"
        manufacturer:
          type: string
          description: Manufacturer of the device
          example: "Nokia"

    DevicePPID:
      description: |
        The individual physical mobile device identifier, expressed as a PPID (Pairwise Pseudonymous Identifier)
      type: object
      properties:
        ppid:
          type: string
          description: A PPID for the identified physical device
          example: "b083f65ccdad365d7489fff24b6d5074b30c12b6d81db3404d25964ffd908813"

    Device:
      description: |
        End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
        The developer can choose to provide the below specified device identifiers:
        * `ipv4Address`
        * `ipv6Address`
        * `phoneNumber`
        * `networkAccessIdentifier`
        NOTE 1: The MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device.
        NOTE 2: For the current Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines.
      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

    DeviceResponse:
      description: |
        An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only returned when the API consumer includes the `device` parameter in their request (i.e. they are using a two-legged access token), and is relevant when more than one device identifier is specified, as only one of those device identifiers is allowed in the response.

        If the API consumer provides more than one device identifier in their request, the API provider must return a single identifier which is the one they are using to fulfil the request, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user.

      allOf:
        - $ref: "#/components/schemas/Device"
        - maxProperties: 1

    DeviceIpv4Addr:
      type: object
      description: |
        The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).

        If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then  the same address should be specified for both publicAddress and privateAddress.

        If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

        In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
      properties:
        publicAddress:
          $ref: "#/components/schemas/SingleIpv4Addr"
        privateAddress:
          $ref: "#/components/schemas/SingleIpv4Addr"
        publicPort:
          $ref: "#/components/schemas/Port"
      anyOf:
        - required: [publicAddress, privateAddress]
        - required: [publicAddress, publicPort]
      example:
        {
          "publicAddress": "84.125.93.10",
          "publicPort": 59765
        }

    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: A human-readable code to describe the error
        message:
          type: string
          description: A human-readable description of what the event represents

    NetworkAccessIdentifier:
      description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
      type: string
      example: "123456789@example.com"

    PhoneNumber:
      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: "+123456789"

    Port:
      description: TCP or UDP port number
      type: integer
      minimum: 0
      maximum: 65535

    RequestBody:
      description: Common request body to allow optional Device object to be passed
      type: object
      properties:
        device:
          $ref: "#/components/schemas/Device"

    SingleIpv4Addr:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: "84.125.93.10"

    DeviceIpv6Address:
      description: |
        The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).
      type: string
      format: ipv6
      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344

    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"

  examples:
    IdentifyDeviceBy3LeggedToken:
      description: Empty JSON when device is identified by access token
      value:
        {}

    IdentifyDeviceByPhoneNumber:
      description: Identifying device by phone number
      value:
        device:
          phoneNumber: "+123456789"

    IdentifyDeviceByIPAddress:
      description: Identifying device by IP address
      value:
        device:
          ipv4Address:
            publicAddress: "84.125.93.10"
            publicPort: 59765

    IdentifyDeviceByMultipleIdentifiers:
      description: Identifying device by multiple device identifiers
      value:
        device:
          phoneNumber: "+123456789"
          ipv4Address:
            publicAddress: "84.125.93.10"
            publicPort: 59765
          networkAccessIdentifier: "123456789@example.com"