openapi: 3.0.0
info:
  title: MAX
  version: 0.1.0
  description: MAX PC-MID API
tags:
  - name: enrol
    description: Enrol an application so that it can use the MAX API.
  - name: roles
    description: Fetch and request roles information.
paths:
  /MAXAPI/venue-api-root-cert:
    get:
      tags:
        - enrol
      summary: Establish trust between client and server
      description: >
        The purpose of visiting this endpoint is to retrieve the Root CA of this
        server's certificate. This is provided so that the client can store the
        Root CA certificate in it's trusted key store.


        When making a request, the client should not verify the server's certificate against a list of certificate authorities (CAs).
      responses:
        "200":
          $ref: "#/components/responses/CACertificate"
  /enrol:
    get:
      tags:
        - enrol
      summary: Establish trust between client and server
      description: >
        The purpose of visiting this endpoint is to make an initial request to
        allow the client and server to handshake, so that the client can use the
        previously retrieved CA to verify the Server's certificate.
      responses:
        "204":
          description: No content
    post:
      tags:
        - enrol
      summary: Enrol with the client's CSR
      description: The purpose of visiting this endpoint is to allow the client to
        upload a certificate signing request (CSR) and for the server to return
        a signed certificate to allow secure communication.
      requestBody:
        content:
          application/pkcs10:
            schema:
              type: string
        description: CSR (certificate signing request)
        required: true
      responses:
        "201":
          description: Enrolment successful
          content:
            application/x-x509-ca-cert:
              schema:
                type: string
                format: binary
            application/x-pem-file:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/InvalidCSR"
        "406":
          $ref: "#/components/responses/CertTypeNotAcceptable"
  /roles:
    get:
      tags:
        - roles
      summary: Fetch information on roles
      description: This purpose of visiting this endpoint is to allow the client to
        find out the status as to whether or not the requested roles have been
        granted or not.
      responses:
        "200":
          $ref: "#/components/responses/RolesResponse"
        "403":
          $ref: "#/components/responses/AccessDenied"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags:
        - roles
      summary: Request roles
      description: This purpose of visiting this endpoint is to allow the client to
        request roles that will provide appropriate permission for the third
        party application type.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RolesRequest"
        description: Roles requested by the client
      responses:
        "201":
          $ref: "#/components/responses/RolesResponse"
        "400":
          $ref: "#/components/responses/RolesBadRequest"
        "403":
          $ref: "#/components/responses/AccessDenied"
servers:
  - url: https://localhost:10098/
components:
  responses:
    CACertificate:
      description: CA certificate
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/CAResponse"
    RolesResponse:
      description: Get roles and permissions info
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/RolesResponse"
    AccessDenied:
      description: User does not have access to page
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/AccessDenied"
    RolesBadRequest:
      description: Bad request
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/APIError"
    NotFound:
      description: Not found
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/APIError"
    InvalidCSR:
      description: Invalid CSR
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/APIError"
    CertTypeNotAcceptable:
      description: Certificate type is not acceptable
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/APIError"
  schemas:
    AccessDenied:
      type: string
    RolesRequest:
      type: object
      required:
        - roles
      properties:
        roles:
          $ref: "#/components/schemas/RolesRequestRoles"
      example:
        roles:
          - superuser
          - venue-api-consumer
    RolesRequestRoles:
      type: array
      items:
        type: string
    APIError:
      type: object
      required:
        - status
        - title
        - detail
      properties:
        status:
          type: string
          description: HTTP status text description
        title:
          type: string
          description: Quick description of the error
        detail:
          type: string
          description: More detail on the error
    CAResponse:
      type: string
    RolesResponse:
      type: object
      properties:
        roles:
          $ref: "#/components/schemas/RolesResponseRoles"
      example:
        roles:
          approved:
            - venue-api-consumer
          desired:
            - jackpot
    RolesResponseRoles:
      type: object
      properties:
        approved:
          type: array
          items:
            type: string
        desired:
          type: array
          items:
            type: string