CAMARA Project Phone number share API

openapi: 3.2.0
info:
  title: Number Verification Phone number share API
  description: '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.'
  version: wip
  x-camara-commonalities: 0.6
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: '{apiRoot}/number-verification/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: Phone Number Share
  description: API operation to return the phone number associated to the access token.
paths:
  /device-phone-number:
    get:
      tags:
      - Phone Number Share
      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:
      - $ref: '#/components/parameters/x-correlator'
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationShareResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
      security:
      - openId:
        - number-verification:device-phone-number:read
components:
  schemas:
    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 '+'.
    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
    NumberVerificationShareResponse:
      type: object
      description: Number verification share result
      required:
      - devicePhoneNumber
      properties:
        devicePhoneNumber:
          $ref: '#/components/schemas/DevicePhoneNumber'
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: b4333c46-49c0-4f62-80d7-f0ef930f1c46
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: '#/components/schemas/XCorrelator'
  responses:
    Generic400:
      description: Problem with the client 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
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param
    PhoneNumberVerificationPermissionDenied403:
      description: "Client does not have sufficient permission.\nIn addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:\n  - 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\"}`)\n"
      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
                  - NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
          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
    Generic401:
      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:
            GENERIC_401_UNAUTHENTICATED:
              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.
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: '#/components/schemas/XCorrelator'
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
externalDocs:
  description: Project documentation at CAMARA
  url: https://github.com/camaraproject/NumberVerification