openapi: 3.0.3
info:
  title: Camara One Time Password
  description: |-
    Service Enabling Network Function API to send short-lived OTPs to a phone number via SMS and validate it afterwards, in order to verify the SMS as a proof of possession.
  version: 0.6.0
  
servers:
  - url: https://api.ooredoo.com
    description: Ooredoo API gateway

paths:
  /oauth/v4/token:
    post:
      summary: Generate Access Token
      description: Token generation endpoint (client_id & client_secret in headers, grant_type & scope in body)
      parameters:
        - name: client_id
          in: header
          required: true
          description: Client ID of onboarded client.
          schema:
            type: string
            format: password
            default: 67Q4itU3ivApTHRB4dJKFh4R5UAdG5RAsMeEq2NppNgd6LBH
        - name: client_secret
          in: header
          required: true
          description: Client secret of onboarded client.
          schema:
            type: string
            format: password
            default: yp1CUQyGwEMNruGXtnhIbpTOuK6BGlxAFmiGlG2FQea3cHgaVqRw7rybKnWAUeKB
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  default: client_credentials
                  description: OAuth grant type
                scope:
                  type: string
                  default: urn:mdv:camaraotp
                  description: OAuth scope
              required:
                - grant_type
                - scope
      responses:
        '200':
          description: Successful token response
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                  expires_in:
                    type: integer
                  consented_on:
                    type: string
                  created_At:
                    type: string
                  expired_At:
                    type: string
        '401':
          $ref: "#/components/responses/Generic401"

  /one-time-password-sms/v4/send-code:
    post:
      summary: Sends a message 
      description: |-
        Sends an SMS with the desired message and an OTP code to the received phone number.
      operationId: sendCode
      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/SendCodeBody'
        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/SendCodeResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/SendCodeForbiddenError403'
        '404':
          $ref: '#/components/responses/Generic404'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
      security:
        - BearerAuth: []          
  
  /one-time-password-sms/v4/validate-code:
    post:
      summary: Verifies the OTP received
      description: |-
        Verifies the code is valid for the received authenticationId
      operationId: validateCode
      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/ValidateCodeBody'
        required: true
      responses:
        '204':
          description: The OTP was successfully validated
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
        '400':
          $ref: '#/components/responses/ValidateCodeBadRequestError400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
      security:
        - BearerAuth: []          

components:
  securitySchemes:
    BearerAuth:
      type: http
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: JWT            
         
  schemas:
    SendCodeBody:
      description: Structure to request sending a code to a phone number
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
        message:
          $ref: '#/components/schemas/Message'
      required:
        - phoneNumber
        - message
    SendCodeResponse:
      description: Structure to provide authentication identifier
      type: object
      properties:
        authenticationId:
          $ref: '#/components/schemas/AuthenticationId'
      required:
        - authenticationId
    ValidateCodeBody:
      description: Strcuture to request code verification
      type: object
      properties:
        authenticationId:
          $ref: '#/components/schemas/AuthenticationId'
        code:
          $ref: '#/components/schemas/Code'
      required:
        - authenticationId
        - code
    PhoneNumber:
      description: MSISDN has to be formatted in international format, according to E.164 standard, prefixed with '+'.
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: '+9609968683'
    Message:
      type: string
      description: Message template. It must include the following label indicating where to include the short code `{{code}}`
      pattern: .*\{\{code\}\}.*
      maxLength: 160
      example: '{{code}} is your short code to authenticate with Cool App via SMS'
    AuthenticationId:
      type: string
      description: unique id of the verification attempt the code belongs to.
      maxLength: 36
      example: ea0840f3-3663-4149-bd10-c7c6b8912105
    Code:
      type: string
      description: temporal, short code to be validated
      maxLength: 10
      example: AJY3
    ErrorInfo:
      description: Structure to describe error
      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:
          description: Correlation id for the different services
          schema:
            type: string
      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
    ValidateCodeBadRequestError400:
      description: |-
        To regular scenario of `INVALID_ARGUMENT`, another scenarios may exist:
          - Too many unsuccessful attempts (`{"code": "ONE_TIME_PASSWORD_SMS.VERIFICATION_FAILED","message": "The maximum number of attempts for this authenticationId was exceeded without providing a valid OTP"}`)
          - Expired authenticationId (`{"code": "ONE_TIME_PASSWORD_SMS.VERIFICATION_EXPIRED","message": "The authenticationId is no longer valid"}`)
          - OTP is not valid for the provided authenticationId (`{"code": "ONE_TIME_PASSWORD_SMS.INVALID_OTP","message": "The provided OTP is not valid for this authenticationId"}`)
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            InvalidArgument:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param
            VerificationFailed:
              value:
                status: 400
                code: ONE_TIME_PASSWORD_SMS.VERIFICATION_FAILED
                message: The maximum number of attempts for this authenticationId was exceeded without providing a valid OTP
            VerificationExpired:
              value:
                status: 400
                code: ONE_TIME_PASSWORD_SMS.VERIFICATION_EXPIRED
                message: The authenticationId is no longer valid
            InvalidOtp:
              value:
                status: 400
                code: ONE_TIME_PASSWORD_SMS.INVALID_OTP
                message: The provided OTP is not valid for this authenticationId
    Generic401:
      description: Authentication problem with the client request
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            message: Request not authenticated due to missing, invalid, or expired credentials
    Generic403:
      description: Client does not have sufficient permission
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 403
            code: PERMISSION_DENIED
            message: Client does not have sufficient permissions to perform this action
    SendCodeForbiddenError403:
      description: |-
        Client does not have sufficient permissions to perform this action.
        In addition to regular scenario of `PERMISSION_DENIED`, another scenarios may exist:
          - Too many code requests were sent (`{"code": "ONE_TIME_PASSWORD_SMS.MAX_OTP_CODES_EXCEEDED","message": "Too many OTPs have been requested for this MSISDN. Try later."}`)
          - The given phoneNumber can't receive an SMS due to business reasons in the operator. (`{"code": "ONE_TIME_PASSWORD_SMS.PHONE_NUMBER_NOT_ALLOWED","message": "Phone_number can't receive an SMS due to business reasons in the operator."}`)
          - The given phoneNumber is blocked to receive SMS due to any blocking business reason in the operator (`{"code": "ONE_TIME_PASSWORD_SMS.PHONE_NUMBER_BLOCKED","message": "Phone_number is blocked to receive SMS due to any blocking business reason in the operator."}`)
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            PermissionDenied:
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action
            MaxOtpCodesExceeded:
              value:
                status: 403
                code: ONE_TIME_PASSWORD_SMS.MAX_OTP_CODES_EXCEEDED
                message: Too many OTPs have been requested for this MSISDN. Try later.
            PhoneNumberNotAllowed:
              value:
                status: 403
                code: ONE_TIME_PASSWORD_SMS.PHONE_NUMBER_NOT_ALLOWED
                message: Phone_number can't receive an SMS due to business reasons in the operator.
            Phone_number_blocked:
              value:
                status: 403
                code: ONE_TIME_PASSWORD_SMS.PHONE_NUMBER_BLOCKED
                message: Phone_number is blocked to receive SMS due to any blocking business reason in the operator.
    Generic404:
      description: Resource Not Found
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            message: A specified resource is not found
    Generic406:
      description: The server can not produce a response matching the content
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 406
            code: NOT_ACCEPTABLE
            message: The server can't produce a response matching the content requested by the client through Accept-* headers
    Generic415:
      description: The server refuses to accept the request because the payload format is in an unsupported format
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 415
            code: UNSUPPORTED_MEDIA_TYPE
            message: The server refuses to accept the request because the payload format is in an unsupported format
    Generic429:
      description: Either out of resource quota or reaching rate limiting
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 429
            code: TOO_MANY_REQUESTS
            message: Either out of resource quota or reaching rate limiting
    Generic500:
      description: Server error
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      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:
          description: Correlation id for the different services
          schema:
            type: string
      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:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 504
            code: TIMEOUT
            message: Request timeout exceeded. Try later.