openapi: 3.0.3
info:
  title: SIM Swap
  description: |
    The SIM Swap API provides a secure, programmable interface for developers and service providers to check the last SIM swap date or verify if a swap occurred within a given period. 
    
    By performing real-time checks, it helps prevent fraud and account takeover by strengthening SIM-based authentication, reducing risks from attackers intercepting SMS one-time passwords or verification codes. 
    
    [GSMA Mobile Connect Account Takeover Protection specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.24-Mobile-Connect-Account-Takeover-Protection-Definition-and-Technical-Requirements-v2.0.pdf) was used as source of input for this API. For more about Mobile Connect, please contact by og_api@ooredoo.com

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:camarasimswap
                  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"

  /sim-swap/v4/retrieve-date:
    post:
      summary: Retrieve SIM swap date
      description: Get timestamp of last SIM swap event for a mobile user account provided with phone number.
      operationId: retrieveSimSwapDate
      requestBody:
        description: |
          Create a SIM swap date request for a phone number.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSimSwapDate"
        required: true
      responses:
        "200":
          description: Contains information about SIM swap change
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimSwapInfo"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "422":
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
        "504":
          $ref: "#/components/responses/Generic504"
      security:
        - BearerAuth: []

  /sim-swap/v4/check:
    post:
      summary: Check SIM swap
      description: Check if SIM swap has been performed during a past period
      operationId: checkSimSwap
      requestBody:
        description: |
          Create a check SIM swap request for a phone number.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCheckSimSwap"
        required: true
      responses:
        "200":
          description: Returns whether a SIM swap has been performed during a past period
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckSimSwapInfo"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "422":
          $ref: "#/components/responses/Generic422"
        "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:
    SimSwapInfo:
      type: object
      required:
        - latestSimChange
      properties:
        latestSimChange:
          type: string
          format: date-time
          description: Timestamp of latest SIM swap performed.
          example: "2023-07-03T14:27:08.312+02:00"
    CheckSimSwapInfo:
      type: object
      required:
        - swapped
      properties:
        swapped:
          type: boolean
          description: Indicates whether the SIM card has been swapped during the period.
    PhoneNumber:
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: '+9609711061'
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
        code:
          type: string
        message:
          type: string
    CreateCheckSimSwap:
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        maxAge:
          type: integer
          example: 240
          minimum: 1
          maximum: 2400
          defaults: 240
    CreateSimSwapDate:
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"

  responses:
    Generic400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
    Generic404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    Generic422:
      description: Unprocessable Content
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    Generic500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    Generic503:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    Generic504:
      description: Gateway Timeout
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"