openapi: 3.0.3
info:
  title: Open-Gateway API V2
  description: >-
    This API provides methods to obtain the capabilities of CAMARA project in
    mas-stack.


    This API can verify or retrieve the **mobile phone number** that is
    currently allocated by the network operator to the SIM in the end user's
    device


    In this API **phone number** refers to the mobile phone number.


    # Introduction


    The Number Verification API is used by the API consumer to perform real-time
    checks to verify the phone number of a mobile device being used to access
    the application. This check can be done either by the API provider,
    returning "true" or "false", or by the application, by matching the phone
    number returned by the API Provider with the phone number of the device that
    is being used.


    It uses silent authentication (Network-based authentication or SIM-Based
    authentication) to verify possession of a phone number in the background
    without requiring user interaction. There are neither one-time passwords
    (OTP) received by SMS nor authenticator app downloads, so it is much
    simpler. It can be used at sign up, login, or transaction time to validate
    that a user's SIM is not spoofed or cloned.


    # Relevant Definitions and Concepts


    - **Network-Based Authentication**: Authentication mechanism based on the
    identification of the mobile phone.

    A network operator knows to which subscriber a connected mobile phone
    belongs and what its associated phone number is.

    - **SIM-Based Authentication**: Authentication mechanism based on the
    identification of the subscriber's SIM installed in the user's device. This
    mechanism relies on temporary tokens provided by the operator, as defined by
    [GSMA
    TS.43](https://www.gsma.com/newsroom/gsma_resources/ts-43-service-entitlement-configuration/)
    and [GSMA ASAC](https://www.gsma.com/newsroom/gsma_resources/asac-01-v1-0/).


    # API Functionality


    This API enables an API Consumer to verify or retrieve the phone number of
    the mobile device being used to access their service.


    # The Authentication Request


    ## Authentication Request with a temporary token


    If the API Consumer has a TS.43 temporary token created on the mobile device
    then this API works over all connections e.g. WiFi taking advantage of the
    SIM-Based authentication.

    The API Consumer sends the temporary token to their backend which sends a
    CIBA Authentication Request, as described in the current release [CAMARA
    APIs Access and User Consent
    Management](https://github.com/camaraproject/IdentityAndConsentManagement),
    with a parameter "login_hint=operatortoken:<temporary token>".

    How the API Consumers get a TS.43 temporary token and how this token is sent
    to their backend, is out-of-scope of the API definition.


    ## Authentication Request without a temporary token


    If the API Consumer does not have a TS.43 temporary token then the API
    Consumer must use OpenId Connect Authorization Code Flow as described in the
    current release of [CAMARA APIs Access and User Consent
    Management](https://github.com/camaraproject/IdentityAndConsentManagement).

    For this method of authentication to work, the device must be connected to
    the mobile network.


    # Resources and Operations overview


    This API currently provides two endpoints which both require a **3-legged
    token** obtained by using one of the two methods indicated in _The
    Authentication Request_ section. This therefore **excludes** using, for
    example, SMS/OTP or user/password as an authentication method:

    - The /verify endpoint checks whether the mobile phone number registered by
    the user with the API consumer matches the one actually associated with the
    mobile device.
      It can receive either a hashed or a plain text phone number as input.
      It compares the received phone number with the user's phone number associated to the access token in order to respond **true/false**.
    - The /device-phone-number endpoint returns the phone number associated by
    the network operator with the SIM in the end user's device.


    # Sequence Diagram


    The following sequence diagram shows an example of a direct integration into
    the developer's application and the API Provider's Authorization Server and
    API for the case that no temporary token is available.


    ![UML Sequence
    Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/documentation/API_documentation/assets/uml_v0.3.jpg)


    **Implementation Details:**


    - **(1):** Authentication must be automatic without any user interactions.
      Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App.

      The API Consumer should use the request parameter prompt=none in the Authentication Request, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensuring no user interaction.

      The API Provider implies the request parameter prompt=none in the Authentication Request for this API.

    - **(2):** The way in which the phone number is retrieved depends upon the
    implementation.
      For example, the access token may be a self-contained encrypted JWT, and so the API provider can decrypt and identify phone number directly from the access token.
      Other implementations might retrieve the phone number associated with the access token from their Authorization Server.

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


    In the case of the Number Verification API scenario and according to the API
    definition, 3-legged access tokens must be used by API clients to invoke
    this API with dedicated scope. The API client must authenticate on behalf of
    a specific user to use this service. This must be done via mobile network
    authentication.
  version: 0.1.0
servers:
  - url: 'https://opengateway.masstack.com/v2/'
    description: production
  - url: 'https://opengateway.sta.masstack.com/v2/'
    description: staging
tags:
  - name: Number Verification
    description: >-
      API operation to verify a phone number received as input. It can be
      received either in plain text or hashed format.
  - name: Phone number share
    description: API operation to return the phone number associated to the access token.
paths:
  '/orgs/{org_id}/number-verification/verify':
    post:
      tags:
        - Number Verification
      summary: >-
        Verifies if the received hashed/plain text phone number matches the
        phone number associated with the access token
      description: >
        Verifies if the specified phone number (either in plain text or hashed
        format) matches the one that the user is currently using. Only one of
        the plain or hashed formats must be provided.

        - The number verification will be done for the user that has
        authenticated via mobile network

        - It returns true/false depending on if the hashed phone number received
        as input matches the authenticated user's `device phone number`
        associated to the access token
      operationId: phoneNumberVerify
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberVerificationVerifyRequest'
            examples:
              PlainExample:
                summary: Plain MSISDN
                value:
                  referenceMsisdn: '+34611223344'
                  evidence:
                    type: PLAIN
                    value: '+34611223344'
              HashedExample:
                summary: HASHED_SHA256 MSISDN
                value:
                  referenceMsisdn: '+34611223344'
                  evidence:
                    type: HASHED_SHA256
                    value: >-
                      32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
        required: true
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationMatchResponse'
        '400':
          $ref: '#/components/responses/NumberVerificationGeneric400'
        '401':
          $ref: '#/components/responses/NumberVerificationGeneric401'
        '403':
          $ref: '#/components/responses/NumberVerificationGeneric403'
        '500':
          $ref: '#/components/responses/NumberVerificationGeneric500'
        '503':
          $ref: '#/components/responses/NumberVerificationGeneric503'
        '504':
          $ref: '#/components/responses/NumberVerificationGeneric504'
  '/orgs/{org_id}/number-verification/device-phone-number':
    get:
      tags:
        - Number Verification
      summary: Returns the phone number associated with the access token
      description: >
        Returns the phone number so the API clients can verify the number
        themselves:

        - It will be done for the user that has authenticated via mobile network

        - It returns the authenticated user's `device phone number` associated
        to the access token
      operationId: phoneNumberShare
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: devicePhoneNumber
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/NumberVerificationDevicePhoneNumber'
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationShareResponse'
        '400':
          $ref: '#/components/responses/NumberVerificationGeneric400'
        '401':
          $ref: '#/components/responses/NumberVerificationGeneric401'
        '403':
          $ref: '#/components/responses/NumberVerificationGeneric403'
        '500':
          $ref: '#/components/responses/NumberVerificationGeneric500'
        '503':
          $ref: '#/components/responses/NumberVerificationGeneric503'
        '504':
          $ref: '#/components/responses/NumberVerificationGeneric504'
components:
  schemas:
    NumberVerificationVerifyRequest:
      type: object
      description: Payload to verify the phone number.
      required:
        - referenceMsisdn
        - evidence
      properties:
        referenceMsisdn:
          type: string
          pattern: '^\+[1-9][0-9]{4,14}$'
          example: '+123456789'
          description: >-
            The MSISDN assigned by the network and extracted from the
            authentication token. 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 '+'.
        evidence:
          type: object
          properties:
            type:
              type: string
              description: >
                Type of evidence provided:

                - `PLAIN`: The MSISDN is provided in plain text.

                - `HASHED_SHA256`: The MSISDN is provided as a hashed value.
                SHA-256 (in hexadecimal representation) of the mobile phone
                number in **E.164 format (starting with country code)**.
                Prefixed with '+'.
              enum:
                - PLAIN
                - HASHED_SHA256
            value:
              type: string
              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 the E.164 standard, prefixed
                with '+'.
          required:
            - type
            - value
    NumberVerificationMatchResponse:
      type: object
      description: Number verification result
      required:
        - devicePhoneNumberVerified
      properties:
        devicePhoneNumberVerified:
          $ref: '#/components/schemas/NumberVerificationDevicePhoneNumberVerified'
    NumberVerificationShareResponse:
      type: object
      description: Number verification share result
      required:
        - devicePhoneNumber
      properties:
        devicePhoneNumber:
          $ref: '#/components/schemas/NumberVerificationDevicePhoneNumber'
    NumberVerificationDevicePhoneNumber:
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: '+123456789'
      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 '+'.
    NumberVerificationDevicePhoneNumberVerified:
      description: 'Number verification. True, if it matches'
      type: boolean
    NumberVerificationApiError:
      type: object
      required:
        - code
        - details
        - ref
        - title
      properties:
        code:
          type: string
          description: code of the error
        title:
          type: string
          description: title of the error
        ref:
          type: string
          description: ref of the error
        details:
          type: string
          description: details of the error
  responses:
    NumberVerificationGeneric400:
      description: Problem with the client request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric403:
      description: >
        Client does not have sufficient permission.

        In addition to regular scenario of `PERMISSION_DENIED`, other scenarios
        may exist:
          - Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"}`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric503:
      description: Service unavailable. Typically the server is down.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric504:
      description: >-
        Request time exceeded. If it happens repeatedly, consider reducing the
        request complexity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
