GSMA Camara Project Number Verification API

openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project Number Verification
  description: >-
    Service Enabling Network Function API to verify that the provided **mobile
    phone number** is the one used in the device. It verifies that the user is
    using a device with the same *mobile phone number* as it is declared. It
    also makes it possible for a Service provider to verify the number itself by
    returning the phone number associated to the authenticated user's access
    token.
  version: 1.0.0
  x-camara-commonalities: 0.4.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: '{apiRoot}/number-verification/v1'
    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: Phone Number Share
    description: API operation to return the phone number associated to the access token.
  - name: Phone Number Verify
    description: >-
      API operation to verify a phone number received as input. It can be
      received either in plain text or hashed format.
paths:
  /verify:
    post:
      tags:
        - Phone Number Verify
      summary: >-
        Global System for Mobile Communications 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:
        - in: header
          name: x-correlator
          required: false
          description: Correlation id for the different services
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberVerificationRequestBody'
        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/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
      security:
        - openId:
            - number-verification:verify
  /device-phone-number:
    get:
      tags:
        - Phone Number Share
      summary: Global System for Mobile Communications 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:
        - in: header
          name: x-correlator
          required: false
          description: Correlation id for the different services
          schema:
            type: string
      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/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
      security:
        - openId:
            - number-verification:device-phone-number:read
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  schemas:
    NumberVerificationRequestBody:
      type: object
      description: Payload to verify the phone number.
      minProperties: 1
      maxProperties: 1
      properties:
        phoneNumber:
          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 '+'.
        hashedPhoneNumber:
          description: >-
            Hashed phone number. SHA-256 (in hexadecimal representation) of the
            mobile phone number in **E.164 format (starting with country
            code)**. Prefixed with '+'.
          type: string
          example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
    NumberVerificationMatchResponse:
      type: object
      description: Number verification result
      required:
        - devicePhoneNumberVerified
      properties:
        devicePhoneNumberVerified:
          $ref: '#/components/schemas/DevicePhoneNumberVerified'
    NumberVerificationShareResponse:
      type: object
      description: Number verification share result
      required:
        - devicePhoneNumber
      properties:
        devicePhoneNumber:
          $ref: '#/components/schemas/DevicePhoneNumber'
    DevicePhoneNumber:
      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 '+'.
    DevicePhoneNumberVerified:
      description: Number verification. True, if it matches
      type: boolean
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
  responses:
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          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.
    PhoneNumberVerificationPermissionDenied403:
      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"}`)
          - Phone number cannot be deducted from access token context.(`{"code": "INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`)
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          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_USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK:
              value:
                status: 403
                code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
                message: >-
                  Client must authenticate via the mobile network to use this
                  service
            GENERIC_403_INVALID_TOKEN_CONTEXT:
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: Phone number cannot be deducted from access token context
    Generic500:
      description: Server error
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: Server error
    Generic503:
      description: Service unavailable. Typically the server is down.
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable
    Generic504:
      description: >-
        Request time exceeded. If it happens repeatedly, consider reducing the
        request complexity
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 504
            code: TIMEOUT
            message: Request timeout exceeded. Try later.
externalDocs:
  description: Project documentation at CAMARA
  url: https://github.com/camaraproject/NumberVerification