openapi: 3.0.3
info:
  title: Open Gateway Onboarding and Ordering (TMF931)
  version: 1.0.0
  description: 'Lets aggregators and channel partners onboard themselves and their customers programmatically, following TM
    Forum TMF931 (Open Gateway Operate API: Onboarding and Ordering). Register an application owner, create applications,
    see which API products are on offer and order access to them, without manual set-up on the portal.'
servers:
- url: https://api.ooredoo.com
  description: Ooredoo API gateway
tags:
- name: Authentication
- name: API products
- name: Onboarding
- name: Ordering
paths:
  /tmf-api/oauth/token:
    post:
      tags:
      - Authentication
      summary: Get an access token
      description: Exchange your app's consumer key and secret for an access token (OAuth 2.0 client credentials).
      operationId: getToken
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              - client_id
              - client_secret
              properties:
                grant_type:
                  type: string
                  enum:
                  - client_credentials
                  example: client_credentials
                client_id:
                  type: string
                  description: Consumer key of your app
                client_secret:
                  type: string
                  description: Consumer secret of your app
      responses:
        '200':
          description: Access token
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: integer
                    example: 3599
        '401':
          description: Invalid client credentials
      security: []
  /tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v1/apiProduct:
    get:
      tags:
      - API products
      summary: List the API products you can order
      operationId: listApiProduct
      responses:
        '200':
          description: API products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiProduct'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token does not carry the scope this operation needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - BearerAuth: []
  /tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v1/applicationOwner:
    post:
      tags:
      - Onboarding
      summary: Register an application owner (your organisation or your customer's)
      operationId: createApplicationOwner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationOwner_Create'
      responses:
        '201':
          description: Application owner created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationOwner'
        '400':
          description: 'Invalid request: a required field is missing or malformed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token does not carry the scope this operation needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - BearerAuth: []
  /tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v1/application:
    post:
      tags:
      - Onboarding
      summary: Create an application for an owner
      operationId: createApplication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application_Create'
      responses:
        '201':
          description: Application created, with its credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          description: 'Invalid request: a required field is missing or malformed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token does not carry the scope this operation needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - BearerAuth: []
  /tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v1/apiProductOrder:
    post:
      tags:
      - Ordering
      summary: Order access to API products for an application
      operationId: createApiProductOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiProductOrder_Create'
      responses:
        '201':
          description: Order accepted
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: 'Invalid request: a required field is missing or malformed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token does not carry the scope this operation needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Access token from the token endpoint
  schemas:
    Error:
      type: object
      properties:
        status:
          type: integer
        code:
          type: string
        message:
          type: string
    ApiProduct:
      type: object
      properties:
        id:
          type: string
          example: SimSwap
        name:
          type: string
          example: Camara SimSwap
        description:
          type: string
    ApplicationOwner_Create:
      type: object
      required:
      - name
      - engagedParty
      properties:
        '@type':
          type: string
          example: ApplicationOwner
        name:
          type: string
          example: Example Aggregator
        description:
          type: string
        engagedParty:
          type: object
          required:
          - name
          - contactMedium
          - organizationIdentification
          properties:
            '@type':
              type: string
              example: Organization
            name:
              type: string
              example: Example Aggregator LLC
            contactMedium:
              type: array
              items:
                type: object
                properties:
                  '@type':
                    type: string
                    example: EmailContactMedium
                  id:
                    type: string
                  emailAddress:
                    type: string
                    example: api@example.com
            organizationIdentification:
              type: array
              items:
                type: object
                required:
                - identificationId
                properties:
                  '@type':
                    type: string
                    example: OrganizationIdentification
                  identificationId:
                    type: string
                    example: CR-123456
            registeredGeographicAddress:
              type: object
              properties:
                city:
                  type: string
                  example: Doha
                countryCode:
                  type: object
                  properties:
                    value:
                      type: string
                      example: QA
    ApplicationOwner:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
    Application_Create:
      type: object
      required:
      - name
      - applicationOwner
      properties:
        '@type':
          type: string
          example: Application
        name:
          type: string
          example: fraud-check-app
        description:
          type: string
        type:
          type: string
        applicationOwner:
          type: object
          required:
          - id
          properties:
            id:
              type: string
              description: ID returned when the owner was created
    Application:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        clientId:
          type: string
        clientSecret:
          type: string
    ApiProductOrder_Create:
      type: object
      required:
      - '@type'
      - email
      - key
      - productOrderItem
      properties:
        '@type':
          type: string
          example: ApiProductOrder
        email:
          type: string
          description: Email of the application owner
          example: api@example.com
        key:
          type: string
          description: Client ID of the application
        productOrderItem:
          type: array
          items:
            type: object
            required:
            - id
            properties:
              id:
                type: string
                description: API product ID from GET /apiProduct
                example: SimSwap