CAMARA Mobile Device Identifier API.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 pairwise pseudonymous identifier (ppid) that the API Producer guaranties to be globally unique, permanent, and pairwise (different for each API consumer)
     - A unique network identifier for the specific device itself (IMEI SV and IMEI)
     - A network identifier for the device make and model (IMEI Type Allocation Code, TAC)
     - Device manufacturer name and model

    This API processes personal user data, and users can exercise their rights through mechanisms such as opt-in and/or opt-out.

    ### Details
    
    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.

    The ppid is independent of the API producer. API producers take care that the ppid is permanent, even in case the device is e.g. sold.
    
    ### Authorization and authentication

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

    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

    ## Handling of mobile subscription information:

    ### Optional mobile subscription identifiers for 3-legged tokens:

    - When using a 3-legged access token, the mobile subscription identifier associated with the access token must be considered as the mobile subscription identifier for the API request. This means that no mobile subscription identifiers are required in the request, and if included it must identify the same subscription. Hence **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations.

    ### Validation mechanism:

    - The API server will determine the mobile subscription identifier (e.g. phone number) from the access token if that information is associated with it (i.e. 3-legged token).
    - If the API request itself additionally includes one or more mobile subscription identifiers when using a 3-legged access token, the API will validate that the identifier(s) provided matches the one associated with the access token.
    - If there is a mismatch, the API will respond with a `403 INVALID_TOKEN_CONTEXT` error, indicating that the mobile subscription information in the request does not match the token.

    ### Error handling for unidentifiable devices:

    - If no mobile subscription information is included in the request and the mobile subscription information cannot be derived from the 3-legged access token, the server will return a `422 UNIDENTIFIABLE_DEVICE` error.

    ### Restrictions for tokens without an associated authenticated identifier:

    - For scenarios which do not have a mobile subscription identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, mobile subscription identifiers MUST be provided in the API request. This ensures that the mobile subscription identifier is explicit and valid for each API call made with these tokens.

    # API functionality

    The API defines service endpoint:

    - `POST /retrieve` to get details about the specific device being used by a given mobile subscriber, including IMEI / IMEISV and the type of device
    
    The API consumer must first obtain a valid OAuth2 token from the token endpoint, which is then passed as an Authorization header. 

    If the authentication token is not valid, a `401 UNAUTHENTICATED` error is returned.

    If the mobile subscription parameters contain a formatting error, a `400 INVALID_ARGUMENT` error is returned.

    If the mobile subscription cannot be identified from the provided parameters, a `404 DEVICE_NOT_FOUND` error is returned.

    If the end user has not consented to the API consumer getting access to the device identifier information, then a `403 PERMISSION_DENIED` error is returned.

    Otherwise, a JSON object is returned containing the data the the end user has consented to sharing with the API consumer. Which data is returned is determined by the scope.
    - 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

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

    ```
    {
       "lastChecked": "2024-02-20T10:41:38.657Z",
       "pairwise": "854a9db5-3239-4cb5-82b2-71540e41ef3d"
    }
    ```

  contact:
    email: sp-dvi@lists.camaraproject.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-camara-commonalities: 0.4.0

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

servers:
  - url: "{apiRoot}/device-identifier/vwip"
    variables:
      apiRoot:
        default: https://localhost:443
        description: API root, to be defined by the service provider

paths:
  "/retrieve":
    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: retrieve
      tags:
        - Get Device Identifiers
      security:
        - openId:
            - device-identifier:pairwise
            - device-identifier:imei
            - device-identifier:imeisv
            - device-identifier:tac
            - device-identifier:model
            - device-identifier:manufacturer

      parameters:
        - in: header
          name: x-correlator
          description: Correlation id for the different services
          required: false
          schema:
            type: string

      requestBody:
        description: Parameters to create a new session
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Device"

      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'
        "405":
          $ref: '#/components/responses/405MethodNotAllowed'
        "406":
          $ref: '#/components/responses/406Unacceptable'
        "422":
          $ref: '#/components/responses/422UnprocessableContent'
        "429":
          $ref: '#/components/responses/429TooManyRequests'
        "500":
          $ref: '#/components/responses/500InternalServerError'
        "502":
          $ref: '#/components/responses/502BadGateway'
        "503":
          $ref: '#/components/responses/503ServiceUnavailable'
        "504":
          $ref: '#/components/responses/504GatewayTimeout'

components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://{apiRoot}.well-known/openid-configuration

  headers:
    X-Correlator:
      description: Correlation id for the different services
      required: false
      schema:
        type: string

  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/LastChecked"
              - $ref: "#/components/schemas/DeviceIdentifier"
              - $ref: "#/components/schemas/DeviceType"

    200RetrieveType:
      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
              - tac
            allOf:
              - $ref: "#/components/schemas/LastChecked"
              - $ref: "#/components/schemas/DeviceType"

    400BadRequest:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InsufficientParameters:
              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"
            InconsistentDeviceProperties:
              description: Device parameters provided identify different devices
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Multiple inconsistent device parameters specified"
            InvalidExternalId:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid format: networkAccessIdentifier"
            InvalidMSISDN:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid format: phoneNumber"
            InvalidIPv4:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid format: ipv4Address"
            InvalidIPv6:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid format: ipv6Address"
            InvalidPort:
              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:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials.
            GENERIC_401_AUTHENTICATION_REQUIRED:
              description: New authentication is needed, authentication is no longer valid
              value:
                status: 401
                code: AUTHENTICATION_REQUIRED
                message: New authentication is required.

    403Forbidden:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            GENERIC_403_PERMISSION_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.
            GENERIC_403_INVALID_TOKEN_CONTEXT:
              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: "{{field}} is not consistent with access token."

    404NotFound:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            GENERIC_404_DEVICE_NOT_FOUND:
              description: Device identifier not found
              value:
                status: 404
                code: DEVICE_NOT_FOUND
                message: Device identifier not found.

    405MethodNotAllowed:
      description: Method Not Allowed
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            MethodNotAllowed:
              description: An HTTP verb other than GET has been used to try and access the resource
              value:
                status: 404
                code: METHOD_NOT_ALLOWED
                message: "The request method is not supported by this resource"

    406Unacceptable:
      description: Not Acceptable
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            NotAcceptable:
              description: A response format other than JSON has been requested
              value:
                status: 406
                code: NOT_ACCEPTABLE
                message: "The server cannot produce a response matching the content requested by the client through Accept-* headers"

    422UnprocessableContent:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
              description: Inconsistency between device identifiers not pointing to the same device
              value:
                status: 422
                code: DEVICE_IDENTIFIERS_MISMATCH
                message: Provided device identifiers are not consistent.
            GENERIC_422_DEVICE_NOT_APPLICABLE:
              description: Service is not available for the provided device
              value:
                status: 422
                code: DEVICE_NOT_APPLICABLE
                message: The service is not available for the provided device.

    429TooManyRequests:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            TooManyRequests:
              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: "Either out of resource quota or reaching rate limiting"

    500InternalServerError:
      description: Internal Server Error
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: 500
            code: INTERNAL
            message: "The service is currently not available"

    502BadGateway:
      description: Bad Gateway
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: 502
            code: BAD_GATEWAY
            message: "The service is currently not available"

    503ServiceUnavailable:
      description: Service Unavailable
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: 503
            code: UNAVAILABLE
            message: "The service is currently not available"

    504GatewayTimeout:
      description: Gateway Time-Out
      headers:
        x-correlator:
          $ref: "#/components/headers/X-Correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: 504
            code: TIMEOUT
            message: "The service is currently not available"

  schemas:
    LastChecked:
      description: |
        Last time that the associated device identity was checked and, if necessary, updated
      properties:
        lastChecked:
          description: Date and time information was last checked
          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"

    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 Commonalities release v0.4, 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

    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
        }

    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: The HTTP status code
        message:
          type: string
          description: This parameter appears when there was an error. Human readable explanation specific to this occurrence of the problem
      required:
        - code
        - status
        - message

    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@domain.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: 1024
      maximum: 65535

    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