openapi: 3.0.0
x-project-id: 'Number_Verify'
info:
  title: Number Verify
  description: |-
    Number Verify checks if the mobile number of a device accessing an online service or app matches the one provided by the customer.

  version: "1.1.1"

servers:
  - url: https://api-sandbox.vf-dmp.engineering.vodafone.com
    description: "Sandbox"
  - url: https://api.vf-dmp.engineering.vodafone.com
    description: "Production"


paths:



  /mobileconnect/premiuminfo/v1/ping:
    get:
      summary: Check the upstream system is up and running.

      security:
        - BasicAuth: []

      operationId: getPing

      parameters:
        - $ref: "#/components/parameters/vf-trace-transaction-id"

      responses:
        '200':
          description: "OK"
          content:
            application/json:
             examples:
              Token response:
                value: {
                       "suffix": "/ping",
                       "client": "35.191.20.68",
                       "startTime": "2023-06-22T16:07:08.868Z",
                       "endTime": "2023-06-22T16:07:08.909Z",
                       "responseTime": 41,
                       "message": "PONG"
                       }
        '400':
            description: "Missing or invalid parameters in request"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "missing client secret"
                    }
        '404':
            description: "URI does not represent a recognised resource"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "URI does not represent a recognised resource"
                    }
        '405':
            description: "The request method is not supported by this resource"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "Method Not Allowed"
                    }
        '406':
            description: "The Accept header is invalid"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "Accept header is invalid"
                    }
        '413':
            description: "The request payload exceeds a maximum size"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "The request payload exceeds a maximum size"
                    }
        '414':
            description: "Request-URI is too long"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "Request-URI is too long"
                    }
        '415':
            description: "The value of the Content-Type header is invalid"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "The value of the Content-Type header is invalid"
                    }
        '422':
            description: "The request was well-formed but was unable to be followed due to semantic errors"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "The request was well-formed but was unable to be followed due to semantic errors"
                    }
        '429':
            description: "Api Quota limit reached"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "Api Quota limit reached"
                    }
        '500':
            description: "The authorization server encountered an unexpected condition that prevented it fromfulfilling the request"
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "The authorization server encountered an unexpected condition that prevented it from fulfilling the request"
                    }

  /mobileconnect/deviceinitiated/v1/authorize:
    get:
      summary: Authorize
      description: |-
        This endpoint is used by the MobileConnect client to request authentication. As the result of the process, the user will obtain a randomly generated code that will be returned to the MobileConnect client via HTTP redirect.

        The destination of the HTTP redirect will be the redirect_uri parameter that you have provided and configured. As part of the security model, if you pass on a redirect_uri that has not been configured initially, the OIDC platform will respond with an error. This is to protect the API so that others are not able to hijack the authentication URL and replace the redirect_uri with their own address to obtain the code.
      parameters:
        - $ref: "#/components/parameters/vf-trace-transaction-id"

        - in: query
          name: redirect_uri
          schema:
            type: string
          required: true
          example : https://www.example.com/consent
          description: Apigee validates this against the list of original redirect URIs registered by the developer for that application. The URL list is separated by characters and provided in the app custom attribute "openid_redirect_uris".

        - in: query
          name: client_id
          schema:
            type: string
          required: true
          example : HKjY453uQ67DahsvAjkG2cdYsOZJddvd
          description: Given when Developer App is created from the Discovery endpoint.

        - in: query
          name: scope
          schema:
            type: string
          required: true
          example : openid mc_vm_match_hash
          description: Space delimited and case-sensitive list of ASCII strings for OAuth 2.0 scope values. OIDC Authorization request MUST contain the scope value **openid mc_vm_match_hash**.

        - in: query
          name: response_type
          schema:
            type: string
          required: true
          example : code
          description: In phase-I one only 'code' is supported. In future we would support all the different flow types as described in openid spec. It must be contain **code**

        - in: query
          name: state
          schema:
            type: string
          required: true
          example : qweqw12414
          description: Generally state is used to maintain state between request and callback.

        - in: query
          name: correlation_id
          schema:
            type: string
          required: false
          example: 42da5b19-457a-4d30-a5c4-038c62dccbb0
          description: Value generated by the SP to uniquely identify a transaction across multiple API calls to the APIx and the IDGW (so we can see the association between /authorize, /token and /premiuminfo requests/responses).

        - in: query
          name: acr_values
          schema:
            type: string
          required: true
          example: 2
          description: Authentication Context class Reference. Space separated string that specifies the Authentication Context Reference to be used during authentication processing. The LOA required by the RP/Client for the use case can be used here. The values appear as order of preference. The acr satisfied during authentication is returned as acr claim value. The recommended values are the LOAs as specified in ISO/IEC 29115 Clause 6 – 1, 2, 3, 4 – representing the LOAs of LOW, MEDIUM, HIGH and VERY HIGH. It’s important to note that mobile connect currently only supports LOAs 2 & 3.The acr_values are indication of what authentication methods to used by the IDP. The authentication methods to be used are linked to the LOA value passed in the acr_values. The IDP configures the authentication method selection logic based on the acr_values. It must be contain **2**

        - in: query
          name: version
          schema:
            type: string
          required: true
          example: mc_di_r2_v2.3
          description: A string value used to identify the profile version. It must be contain **mc_di_r2_v2.3**.

        - in: query
          name: nonce
          schema:
            type: string
          required: true
          example: 42da5b19-457a-4d30-a5c4-038c62dccbb0
          description: String value used to associate a client session with the ID Token. It is passed unmodified from Authorisation Request to ID Token. The value SHOULD be unique per session to mitigate replay attacks.

      responses:
        '302':
          description: |-
            **Found**
            Redirects to either Vodafone ID page of redirect uri of client

            in **Location** Header:

            - In seccess cases a 302 response would contain a **code** to be used in the token api request

                  https://www.example.com/consent?code=gRIk9pak&state=4efbd576-4622-4042-ba13-adb0a6b00a25

            - In failure cases a 302 response would contain **error** and **error_description** fields in query parameter

                  https://www.example.com/consent?error=interaction_required&error_description=customerData_not_found_during_networkLogin_for_MSISDN&state=ee07fc69-0f9d-43d6-b93a-bcb4c7e6be20


  /mobileconnect/deviceinitiated/v1/token:
    post:
      summary: Token

      security:
        - BasicAuth: []

      description: |-
            The service provide a one-time **access_token** that must be used to call the premiuminfo endpoint.

            Basic Authorization is required to perform the request: an Authorization header with "Basic <base64(clientId:secret)>", e.g.:

              **Authorization: Basic ajBXV1B5eWRrTFFpN0FvRk5GfjyrQTZwcTZwZFVsSjA6IHI1OGdpdUJMbGRHSEIxMmQ**

      operationId: getToken

      parameters:
        - $ref: "#/components/parameters/vf-trace-transaction-id"

      requestBody:
        description: |-
          Token end point is used to generate oauth2 access token.

        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - code
                - redirect_uri
                - grant_type
              properties:
                redirect_uri:
                  type: string
                  example: https://www.example.com/consent
                  description: It should be same value which was provided in /authorize call
                grant_type:
                  type: string
                  example: authorization_code
                  description: only allowed value is authorization_code
                code:
                  type: string
                  example: 123124
                  description: authorization code which is obtained via open id connect flow.

      responses:
        '200':
          description: "OK"
          content:
            application/json:
             examples:
              Token response:
                value: {
                      "access_token": "bGzoVULW9RiZGBK1CLC4lZGsNuVm",
                      "token_type": "Bearer",
                      "expires_in": 3599,
                      "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaWRldi5kZXZlbG9wZXIudm9kYWZvbmUuY29tIiwic3ViIjoiODhlMzk5ZWUtYmE5Zi00ZmVmLTk0NDUtMDE2YjAzNjU5OTkxIiwiYXVkIjoiODN0RmVzQmhJVEJBVEExa2hxbzJvekYzQ01Mb0k3blUiLCJleHAiOjM1OTkwMDEsImlhdCI6MSwiYXV0aF90aW1lIjoiMS41MjAzMTQ5NDhFOSIsIm5vbmNlIjoiMTIzNCIsImFjciI6IjMiLCJuYW1lIjoiSmFuZSBEb2UiLCJnaXZlbl9uYW1lIjoiSmFuZSIsImZhbWlseV9uYW1lIjoiRG9lIiwibWlkZGxlX25hbWUiOiJydXRoIiwibmlja25hbWUiOiJqb2UiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJqLmRvZSIsInByb2ZpbGUiOiJodHRwczovL2dvb2dsZS5jb20iLCJwaWN0dXJlIjoiaHR0cHM6Ly9waWN0dXJlcy5jb20iLCJ3ZWJzaXRlIjoiaHR0cHM6Ly93ZWJzaXRlLmNvbSIsImdlbmRlciI6Ik1hbGUiLCJ6b25laW5mbyI6IkV1cm9wZS9QYXJpcyIsImxvY2FsZSI6IkVOIiwidXBkYXRlZF9hdCI6IjEyMzQ1Njc4OTAiLCJhZGRyZXNzIjp7InN0cmVldF9hZGRyZXNzIjoiU0JJIENvbG9ueSIsImxvY2FsaXR5IjoiS29yYW1hbmdsYSIsInJlZ2lvbiI6IkJhbmdhbG9yZSIsInBvc3RhbF9jb2RlIjoiNTYwMDM0IiwiY291bnRyeSI6IkluZGlhIn0sImVtYWlsIjoiamFuZWRvZUBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjoidHJ1ZSIsInBob25lX251bWJlciI6IjkzNzg2NTM0MTIiLCJwaG9uZV9udW1iZXJfdmVyaWZpZWQiOiJ0cnVlIiwiY3JpZCI6IjEyMzQiLCJsb2NhbF9zdWIiOiIwOTIyYmQ3Zi1kZDhkLTRjYTAtODEzNS05M2RkOTUxMjZjODMifQ.GwHvOTBbpcO-Y2aXOmuruXl8qQthkpOssHyTxFjpZTw"
                    }
        '400':
            description: Bad Request
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "The request contains the same parameter multiple times"
                    }
        '401':
            description: Unauthorized
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "Missing or invalid client_id or client_secret"
                    }
        '404':
            description: Not Found
            content:
              application/json:
                example:
                    {
                     "error": "Resource Not Found",
                      "error_description": "URI does not represent a recognised resource"
                    }
        '405':
            description: Method Not Allowed
            content:
              application/json:
                example:
                    {
                     "error": "Method Not Allowed",
                      "error_description": "The request method is not supported by this resource"
                    }
        '406':
            description: Not Acceptable
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "Accept header is invalid"
                    }
        '413':
            description: Payload Too Large
            content:
              application/json:
                example:
                    {
                     "error": "Payload Too Large",
                      "error_description": "The request payload exceeds a maximum size"
                    }
        '414':
            description: "Request URI Too Long"
            content:
              application/json:
                example:
                    {
                     "error": "Request URI Too Long",
                      "error_description": "Request-URI is too long"
                    }
        '415':
            description: Unsupported Media Type
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "The value of the Content-Type header is invalid"
                    }
        '422':
            description: Unprocessable Content
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "The request was well-formed but was unable to be followed due to semantic errors"
                    }
        '429':
            description: Too Many Requests
            content:
              application/json:
                example:
                    {
                     "error": "invalid_request",
                      "error_description": "Api Quota limit reached"
                    }
        '500':
            description: Internal Server Error
            content:
              application/json:
                example:
                    {
                     "error": "Internal Server Error",
                      "error_description": "The authorization server encountered an unexpected condition that prevented it from fulfilling the request"
                    }


  /mobileconnect/premiuminfo/v1:
    post:
      summary: Premiuminfo

      description: |-
        The premiuminfo endpoint is an protected resource which returns claims about the authenticated end-user.

        This resource is used by a service provider to initiate an OpenID/Mobile Connect authorization.

        Bearer Authentication is required to perform the request: an Authorization header with the access_token retrieved with the token API request, e.g.:

          **Authorization: Bearer alEw85xBVY83owVraNwNxzsfmpXu**

      security:
        - BearerAuth: []

      operationId: getPremiumInfo

      parameters:
        - $ref: "#/components/parameters/vf-trace-transaction-id"
        - $ref: "#/components/parameters/VF_EXT_BP_ID"

      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/mc_claims"
            examples:
              Scope - openid mc_vm_match_hash with:
                value: {
                       "mc_claims":{
                          "device_msisdn_hash":"43e851329a56ca2da61fd69b48554527a1425937d8b1cee06f4d8990ad0e4476"
                       }
                    }

      responses:
        '200':
          description: "**OK**"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/mc_response"



        '400' :
          description: |
              **Bad request**
          content:
            application/json:
              examples:
                Unknown user:
                  value: {
                           "error": "access_denied",
                           "error_description": "Unknown user.",
                          }
                invalid msisdn:
                  value: {
                           "error": "invalid_request",
                           "error_description": "Invalid User-ID value: invalid format",
                          }
                invalid request:
                  value: {
                           "error": "invalid_request",
                           "error_description": "User-ID / User-ID-Type header is not used and the Access Token is not tied to an End-User",
                          }
                not whitelisted country:
                  value: {
                           "error": "invalid_request",
                           "error_description": "Service is not whitelisted for this country",
                          }
                invalid_scope:
                  value: {
                           "error": "invalid_scope",
                           "error_description": "The scope is valid but not associated with this API"
                          }


        '401' : # invalid_client
          description: |
              **Unauthorized**
          content:
            application/json:
              examples:
                invalid_client:
                  value: {
                    "error": "invalid_client",
                    "error_description": "Invalid Access Token"
                  }

        '404' :
          description: |
              **Not Found**
          content:
            application/json:
              examples:
                Resource Not Found:
                  value: {
                    "error": "Resource Not Found",
                    "error_description": "URI does not represent a recognised resource",
                  }
        '405' :
          description: |
              **Method Not Allowed**
          content:
            application/json:
              examples:
                Method Not Allowed:
                  value: {
                    "error": "Method Not Allowed",
                    "error_description": "The request method is not supported by this  resource",
                  }
        '406' :
          description: |
              **Not Acceptable**
          content:
            application/json:
              examples:
                Not Acceptable:
                  value: {
                    "error": "Not Acceptable",
                    "error_description": "The Accept header is invalid ",
                  }
        '413' :
          description: |
              **Payload Too Large**
          content:
            application/json:
              examples:
                Payload Too Large:
                  value: {
                    "error": "Payload Too Large",
                    "error_description": "The  response payload exceeds a maximum size.",
                  }
        '414' :
          description: |
              **Request URI Too Long**
          content:
            application/json:
              examples:
                Request URI Too Long:
                  value: {
                    "error": "Request URI Too Long",
                    "error_description": "Request-URI is too long",
                  }

        '415' :
          description: |
              **Unsupported Media Type**
          content:
            application/json:
              examples:
                Unsupported Media Type:
                  value: {
                    "error": "invalid_request",
                    "error_description": "The value of the Content-Type header is invalid",
                  }
        '422' :
          description: |
              **Unprocessable Entity**
          content:
            application/json:
              examples:
                Unprocessable Entity:
                  value: {
                    "error": "Unprocessable Entity",
                    "error_description": "The request was well-formed but was unable to be followed due to semantic errors",
                  }
        '429' :
          description: |-
              **Too Many Requests**
          content:
            application/json:
              examples:
                Api Quota limit reached:
                  value: {
                    "error": "Too Many Requests",
                    "error_description": "Api Quota limit reached ",
                  }
                OpCo Quota limit reached:
                  value: {
                    "error": "Too Many Requests",
                    "error_description": "OpCo Quota limit reached",
                  }
                End-User limit based on $1 has been reached:
                  value: {
                    "error": "Too Many Requests",
                    "error_description": "End-User limit based on $1 has been reached",
                  }

        '431' :
          description: |
              **Request Header Fields Too Large**
          content:
            application/json:
              examples:
                Request Header Fields Too Large:
                  value: {
                    "error": "Request Header Fields Too Large",
                    "error_description": "The server is unwilling to process the request because either an individual header field, or all the header fields collectively, are too large",
                  }

        '500' :
          description: |
              **Internal Server Error**
          content:
            application/json:
              examples:
                Internal Server Error:
                  value: {
                           "error": "server_error",
                           "error_description": "Internal Server Error."
                          }

                Service unavailable:
                  value: {
                           "error": "server_error",
                           "error_description": "The service is currently not available. Please try again later."
                          }

components:
  schemas:
    mc_claims:
      type: object
      description: |-
        The mc_claims object contains the hashed MSISDN

      required:
        - device_msisdn_hash

      properties:
        device_msisdn_hash:
              type: object
              description: |-
                The hashed MSISDN to be matched against the one ontained by Header Enrichment
              properties:
                value:
                  type: string

    mc_response:
        type: object
        required:
          - device_msisdn_verified
        properties:
          device_msisdn_verified:
            type: boolean
            description: 'True if the MSISDN is matched else false.'
            example: true
          correlation_id:
            type: string
            description: 'A unique use case ID used for logging and end-to-end tracing.Value used to associate all calls from the SP to IDGW (and other components) for each transaction'
            example: 688c911a-92d4-11e7-abc4-cec278b6b50a
          sub:
            type: string
            description: 'Subject identifier. A globally unique identifier (PCR) of the end -user to work in a federated environment. It is a case-sensitive ASCII string with a maximum length of 255. The sub value MUST not contain the MSISDN.'
            example: 98ewq9ewqh9ewq87h9ewqe8h9wehw9e


  securitySchemes:

    BasicAuth:
        type: http
        scheme: basic

    BearerAuth:
      type: http
      scheme: bearer

  parameters:
    vf-trace-transaction-id:
      name: vf-trace-transaction-id
      in: header
      required: false
      description: A unique identifier for each request (typically a GUID).  Not defined as part of the standard but can be utilized by the SP to set a value which could assist in troubleshooting.  Note that if this header is not set in the request, Vodafone generates this value upon receipt of the message and returns the value in the response as a header.
      schema:
        type: string
    VF_EXT_BP_ID:
      name: VF_EXT_BP_ID
      in: header
      required: false
      description: The "VF_EXT_BP_ID" header holds the Client Origin Id. This is a means for identifying the originating customer. The value of Client Origin Id can be up to 12 characters in length, and it can contain a combination of A-Z, a-z, underscore and hyphen characters as permitted values. (No other special characters/white space is permitted). The value of the Client Origin ID will be assigned by Vodafone and communicated to the appropriate customer team.
      schema:
        type: string
