openapi: 3.0.0
info:
  title: Polito Faculty Announcements Auth API
  version: 0.0.1
  license:
    name: CC BY-NC 4.0
    url: https://creativecommons.org/licenses/by-nc/4.0/
servers:
- url: https://app.didattica.polito.it/api
  description: Production server
  variables: {}
- url: https://app.didattica.polito.it/mock/api
  description: Mock server (uses example data)
  variables: {}
security:
- BearerAuth: []
tags:
- name: Auth
paths:
  /auth/client:
    patch:
      operationId: Auth_appInfo
      summary: Update client version fields | Aggiorna i campi di versione del client
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UpdateInfo'
                required:
                - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppInfoRequest'
  /auth/login:
    post:
      operationId: Auth_login
      summary: Login
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Identity'
                required:
                - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      security:
      - {}
  /auth/logout:
    delete:
      operationId: Auth_logout
      summary: Logout
      description: Invalidates the provided token
      parameters: []
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
  /auth/mfa/challenge:
    get:
      operationId: Mfa_fetchChallenge
      summary: Fetch pending challenge
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/MfaChallenge'
                    nullable: true
                required:
                - data
              example:
                data:
                  serial: EDUP000123456
                  challenge: dGhpcyBzaG91bGQgYmUgYW4gZWNkcyBwdWJsaWMga2V5Li4uIHdoYXQgZGlkIHlvdSB0aGluayB0aGlzIHdhcz8hIPCfp5AK
                  requestTs: '2025-01-01T00:00:00Z'
                  expirationTs: '2025-01-01T01:00:00Z'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
  /auth/mfa/enrol:
    post:
      operationId: Mfa_enrolMfa
      summary: Enroll a new PUSH token
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      serial:
                        type: string
                        example: EDUP000123456
                    required:
                    - serial
                required:
                - data
              example:
                data:
                  serial: EDUP000123456
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrolMfaRequest'
  /auth/mfa/status:
    get:
      operationId: Mfa_getMfaStatus
      summary: Get MFA status for the current user
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MfaStatusResponse'
                required:
                - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
  /auth/mfa/validate:
    post:
      operationId: Mfa_validateMfa
      summary: Validate a challenge
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                    required:
                    - success
                required:
                - data
              example:
                data:
                  success: true
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateMfaRequest'
  /auth/serviceLink/liveClass/{meetingID}:
    get:
      operationId: ServiceLink_getLiveClassLink
      summary: Get authorised service link for LiveClass meeting
      parameters:
      - name: meetingID
        in: path
        required: true
        description: LiveClass meeting identifier
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LinkToService'
                required:
                - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
  /auth/serviceLink/mail:
    get:
      operationId: ServiceLink_getMailLink
      summary: Get authorised service link for Mail
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LinkToService'
                required:
                - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
  /auth/serviceLink/moodle/{course}:
    get:
      operationId: ServiceLink_getMoodleLink
      summary: Get authorised service link for Moodle course
      parameters:
      - name: course
        in: path
        required: true
        description: Moodle course identifier
        schema:
          type: integer
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LinkToService'
                required:
                - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
  /auth/switch-career:
    post:
      operationId: Auth_switchCareer
      summary: Switch career | Cambia carriera
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Identity'
                required:
                - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchCareerRequest'
components:
  schemas:
    UpdatePreferencesRequest:
      type: object
      properties:
        language:
          type: string
          enum:
          - it
          - en
          example: it
    LoginRequest:
      type: object
      oneOf:
      - $ref: '#/components/schemas/LoginCredentialsBasic'
      - $ref: '#/components/schemas/LoginCredentialsSSO'
      discriminator:
        propertyName: loginType
        mapping:
          basic: '#/components/schemas/LoginCredentialsBasic'
          sso: '#/components/schemas/LoginCredentialsSSO'
    EnrolMfaRequest:
      type: object
      required:
      - description
      - pubkey
      properties:
        description:
          type: string
          example: some identifier you chose
        pubkey:
          type: string
          example: dGhpcyBzaG91bGQgYmUgYW4gZWNkcyBwdWJsaWMga2V5Li4uIHdoYXQgZGlkIHlvdSB0aGluayB0aGlzIHdhcz8hIPCfp5AK
      example:
        description: some identifier you chose
        pubkey: dGhpcyBzaG91bGQgYmUgYW4gZWNkcyBwdWJsaWMga2V5Li4uIHdoYXQgZGlkIHlvdSB0aGluayB0aGlzIHdhcz8hIPCfp5AK
    UpdateInfo:
      type: object
      required:
      - suggestUpdate
      properties:
        suggestUpdate:
          type: boolean
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    MfaStatusResponse:
      type: object
      required:
      - status
      - details
      properties:
        status:
          type: string
          enum:
          - active
          - locked
          - available
          - unavailable
          - needsReauth
          description: Current MFA status for the user
        details:
          type: object
          properties:
            lastAuth:
              type: string
              format: date-time
              example: '2021-09-30T00:00:00Z'
            authCount:
              type: integer
              example: 1
            serial:
              type: string
              example: EDUP0000123456
            description:
              type: string
              example: My phone
          required:
          - lastAuth
          - authCount
          nullable: true
          description: 'Additional information about the MFA session.

            Present only if status is `active` or `locked`'
    LoginCredentialsSSO:
      type: object
      required:
      - uid
      - key
      - loginType
      properties:
        uid:
          type: string
          example: 123456-1234-5678-123456
        key:
          type: string
          example: abcdef-abcd-efgh-abcdef
        loginType:
          type: string
          enum:
          - sso
      allOf:
      - $ref: '#/components/schemas/LoginRequestBase'
    Client:
      type: object
      required:
      - buildNumber
      - appVersion
      - name
      properties:
        buildNumber:
          type: string
          example: '1060200'
        appVersion:
          type: string
          example: 1.6.2
        fcmRegistrationToken:
          type: string
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
        name:
          type: string
          example: Students app
        id:
          type: string
          example: 5a54f626-4b7e-488e-a0e3-300f54051510
    Device:
      type: object
      required:
      - platform
      - toothPicCompatible
      properties:
        name:
          type: string
        platform:
          type: string
        version:
          type: string
        model:
          type: string
        manufacturer:
          type: string
        toothPicCompatible:
          type: boolean
    ValidateMfaRequest:
      type: object
      required:
      - serial
      - nonce
      - signature
      properties:
        serial:
          type: string
          example: EDUP000123456
        nonce:
          type: string
          example: 65ba9e0e5aac421a9150991638a9d697
        signature:
          type: string
          example: 83e08d9fc4be3de046318eb3c2c9ae4ede1374a5423a1487b92febc70d106994
        decline:
          type: boolean
          example: false
      example:
        serial: EDUP000123456
        nonce: 65ba9e0e5aac421a9150991638a9d697
        signature: 83e08d9fc4be3de046318eb3c2c9ae4ede1374a5423a1487b92febc70d106994
        decline: false
    LoginRequestBase:
      type: object
      required:
      - preferences
      properties:
        client:
          $ref: '#/components/schemas/Client'
        device:
          $ref: '#/components/schemas/Device'
        preferences:
          $ref: '#/components/schemas/UpdatePreferencesRequest'
    LoginCredentialsBasic:
      type: object
      required:
      - username
      - password
      - loginType
      properties:
        username:
          type: string
          example: s290683
        password:
          type: string
          example: moreSecret
        loginType:
          type: string
          enum:
          - basic
      allOf:
      - $ref: '#/components/schemas/LoginRequestBase'
    Identity:
      type: object
      required:
      - username
      - type
      - clientId
      - token
      properties:
        username:
          type: string
          example: s290683
        type:
          type: string
          example: student
        clientId:
          type: string
          example: 5a54f626-4b7e-488e-a0e3-300f54051510
        token:
          type: string
          example: c679fa38ff665df6a676acd833194385
      example:
        username: s290683
        type: student
        clientId: 5a54f626-4b7e-488e-a0e3-300f54051510
        token: c679fa38ff665df6a676acd833194385
    AppInfoRequest:
      type: object
      properties:
        buildNumber:
          type: string
          example: '1060200'
        appVersion:
          type: string
          example: 1.6.2
        fcmRegistrationToken:
          type: string
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
    MfaChallenge:
      type: object
      required:
      - serial
      - challenge
      - requestTs
      - expirationTs
      properties:
        serial:
          type: string
          example: EDUP000123456
        challenge:
          type: string
          example: dGhpcyBzaG91bGQgYmUgYW4gZWNkcyBwdWJsaWMga2V5Li4uIHdoYXQgZGlkIHlvdSB0aGluayB0aGlzIHdhcz8hIPCfp5AK
        requestTs:
          type: string
          format: date-time
          example: '2025-01-01T00:00:00Z'
        expirationTs:
          type: string
          format: date-time
          example: '2025-01-01T01:00:00Z'
    SwitchCareerRequest:
      type: object
      required:
      - username
      properties:
        username:
          type: string
          example: s290683
        client:
          $ref: '#/components/schemas/Client'
        device:
          $ref: '#/components/schemas/Device'
      example:
        username: s290683
    LinkToService:
      type: object
      required:
      - url
      properties:
        url:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer