info:
  version: 1.48.0
  title: IT Academy SSO Service
  description: This is an SSO service that is used across all ITA services.
openapi: 3.0.0
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    cookieAuth:
      type: apiKey
      in: cookie
      name: authToken
  headers:
    Set-Cookie:
      schema:
        type: string
        example: authToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjbGdieTNyemYwMDAweG44eDdzeXJvMnc2IiwiaWF0IjoxNjgxMjEyNzAzLCJleHAiOjE2ODEyOTkxMDN9.G1F5XQLYu0uwxnJDx_qDUV3avIUPxHb3Ld-XZYvUfNM;
          path=/; httponly
        description: Sets the JWT session cookie
  schemas:
    EmailError:
      type: object
      properties:
        message:
          type: string
          example: email or dni already exists
      required:
        - message
    InputError:
      type: object
      properties:
        message:
          type: string
          example: Input is not a string
      required:
        - message
    MissingTokenError:
      type: object
      properties:
        message:
          type: string
          example: Missing token
      required:
        - message
    InvalidTokenError:
      type: object
      properties:
        message:
          type: string
          example: Token is not valid
      required:
        - message
    ForbiddenError:
      type: object
      properties:
        message:
          type: string
          example: Only active users can login
      required:
        - message
    MissingUserError:
      type: object
      properties:
        message:
          type: string
          example: User not found
      required:
        - message
    ValidationError:
      type: object
      properties:
        message:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: invalid_string
              message:
                type: string
                example: Invalid
              validation:
                type: string
                example: regex
              expected:
                type: string
                example: string
              received:
                type: string
                example: undefined
            required:
              - code
              - message
      required:
        - message
    InvalidCredentialsError:
      type: object
      properties:
        message:
          type: string
          example: Invalid Credentials
      required:
        - message
    DeletedUserError:
      type: object
      properties:
        message:
          type: string
          example: User already deleted
      required:
        - message
  parameters: {}
paths:
  /api/v1/auth/login:
    post:
      tags:
        - auth
      operationId: postLogin
      description: Takes a DNI and a password and returns authToken and refreshToken
      summary: Logs in a user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dni:
                  type: string
                password:
                  type: string
                  minLength: 8
              required:
                - dni
                - password
      responses:
        "200":
          description: The user has been authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  authToken:
                    type: string
                    minLength: 1
                  refreshToken:
                    type: string
                    minLength: 1
                  id:
                    type: string
                required:
                  - authToken
                  - refreshToken
                  - id
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "403":
          description: Forbidden error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
  /api/v1/auth/register:
    post:
      tags:
        - auth
      operationId: postRegister
      description: Takes a DNI, email and a password and registers a new user in the
        database. No object is returned.
      summary: Register a user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dni:
                  type: string
                email:
                  type: string
                  minLength: 1
                  format: email
                  example: user@example.cat
                name:
                  type: string
                  minLength: 1
                  example: John Doe
                itineraryId:
                  type: string
                password:
                  type: string
                  minLength: 8
                  pattern: ^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]*$
                confirmPassword:
                  type: string
                  minLength: 8
                  pattern: ^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]*$
              required:
                - dni
                - email
                - name
                - itineraryId
                - password
                - confirmPassword
      responses:
        "200":
          description: The user has been registered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: b6z2od3ut12qs0ilem6njgjp
                required:
                  - id
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "409":
          description: Email or User already exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailError"
        "422":
          description: Invalid itinerary ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid itinerary
                required:
                  - message
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/tokens/validate:
    post:
      tags:
        - tokens
      operationId: postValidateTokens
      description: Validates a given authentication token.
      summary: Validate a Token
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                authToken:
                  type: string
                  minLength: 1
              required:
                - authToken
              additionalProperties: false
      responses:
        "200":
          description: The token is valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: b6z2od3ut12qs0ilem6njgjp
                required:
                  - id
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/tokens/refresh:
    post:
      tags:
        - tokens
      operationId: postRefreshTokens
      description: Allows clients to obtain a new access token using a valid refresh
        token. Ensure to send the refresh token as a Bearer token in the
        Authorization header. This method extends user sessions securely without
        re-entering login credentials.
      summary: Renew Access Token
      security:
        - bearerAuth: []
      responses:
        "200":
          description: The token is valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  authToken:
                    type: string
                    minLength: 1
                required:
                  - authToken
                additionalProperties: false
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/itineraries:
    get:
      tags:
        - itineraries
      operationId: listItineraries
      description: Fetches all available itineraries
      summary: Get all itineraries
      responses:
        "200":
          description: List of all itineraries
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                      example: Frontend Angular
                    slug:
                      type: string
                      example: frontend-angular
                  required:
                    - id
                    - name
                    - slug
  /api/v1/users/me:
    post:
      tags:
        - users
      operationId: postMe
      description: Returns information of a logged in user. Token received in the
        login necessary.
      summary: Get user information
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                authToken:
                  type: string
                  minLength: 1
              required:
                - authToken
              additionalProperties: false
      responses:
        "200":
          description: Token is valid and user information is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dni:
                    type: string
                  email:
                    type: string
                    minLength: 1
                    format: email
                    example: user@example.cat
                  role:
                    type: string
                    enum:
                      - ADMIN
                      - MENTOR
                      - REGISTERED
                required:
                  - dni
                  - email
                  - role
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/users/{id}:
    patch:
      tags:
        - users
      operationId: patchUsers
      description: Allows a logged in ADMIN user to modify another user.
      summary: Patch a user.
      parameters:
        - in: path
          name: id
          schema:
            type: string
            example: b6z2od3ut12qs0ilem6njgjp
          required: true
      requestBody:
        required: true
        description: Updates an existing user. The ID is mandatory, and all other fields
          are optional. Provide only the fields that need to be updated.
        content:
          application/json:
            schema:
              type: object
              properties:
                authToken:
                  type: string
                  minLength: 1
                dni:
                  type: string
                email:
                  type: string
                  minLength: 1
                  format: email
                  example: user@example.cat
                name:
                  type: string
                  minLength: 1
                  example: John Doe
                password:
                  type: string
                  minLength: 8
                role:
                  type: string
                  enum:
                    - ADMIN
                    - MENTOR
                    - REGISTERED
                status:
                  type: string
                  enum:
                    - ACTIVE
                    - PENDING
                    - BLOCKED
                deletedAt:
                  type: string
                  nullable: true
                  format: date-time
                itineraryId:
                  type: string
              required:
                - authToken
              additionalProperties: false
      responses:
        "204":
          description: User has been modified
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Invalid token or missing token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/users:
    get:
      tags:
        - users
      operationId: listUsers
      description: Returns id and name information of users.
      summary: Get list of users name information with given id array
      parameters:
        - in: query
          name: id
          schema:
            type: array
            items:
              type: string
              example: b6z2od3ut12qs0ilem6njgjp
          required: true
          description: user id
          explode: false
        - in: query
          name: fields
          schema:
            type: array
            items:
              type: string
              enum:
                - id
                - name
          required: false
          description: Specify fields to return (id, name)
          explode: false
      responses:
        "200":
          description: Token is valid and user information is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: b6z2od3ut12qs0ilem6njgjp
                    name:
                      type: string
                      minLength: 1
                      example: John Doe
                  required:
                    - id
                    - name
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/dashboard/auth/login:
    post:
      tags:
        - dashboard
      operationId: postDashboardLogin
      description: Takes a DNI and a password and returns authToken and refreshToken cookie
      summary: Logs in a user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dni:
                  type: string
                password:
                  type: string
                  minLength: 8
              required:
                - dni
                - password
      responses:
        "204":
          description: The user has been authenticated
          headers:
            Set-Cookie:
              $ref: "#/components/headers/Set-Cookie"
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "403":
          description: Forbidden error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
  /api/v1/dashboard/auth/logout:
    post:
      tags:
        - dashboard
      operationId: postDashboardLogout
      description: Deletes cookie and logouts user
      summary: Logs out user
      responses:
        "204":
          description: User has been logged out successfully
  /api/v1/dashboard/users:
    get:
      tags:
        - dashboard
      operationId: listDashboardUsers
      description: Returns id, name, dni, itinerary, status, role, deletedAt and
        created at information of users.
      summary: Get list of users name information
      security:
        - cookieAuth: []
      parameters:
        - in: query
          name: itinerarySlug
          schema:
            type: string
            example: frontend-angular
          required: false
          description: Slug of the itinerary for which to retrieve users by itineraries
          example: frontend-angular
        - in: query
          name: status
          schema:
            type: string
            enum:
              - ACTIVE
              - PENDING
              - BLOCKED
              - DELETED
          required: false
          description: Status to filter by
          example: ACTIVE
        - in: query
          name: startDate
          schema:
            type: string
            nullable: true
            format: date
          required: false
          description: Start date to filter users by, format YYYY-MM-DD
          example: 2023-03-05
        - in: query
          name: endDate
          schema:
            type: string
            nullable: true
            format: date
          required: false
          description: End date to filter users by, format YYYY-MM-DD
          example: 2026-03-05
        - in: query
          name: name
          schema:
            type: string
            minLength: 2
            example: John Doe
          required: false
          description: Partial or full name to filter the users by
        - in: query
          name: dni
          schema:
            type: string
            minLength: 2
            maxLength: 9
          required: false
          description: Partial or full dni to filter the users by
        - in: query
          name: role
          schema:
            type: string
            enum:
              - ADMIN
              - MENTOR
              - REGISTERED
          required: false
          description: Role to filter by
          example: ADMIN
      responses:
        "200":
          description: Token is valid and user information is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: b6z2od3ut12qs0ilem6njgjp
                    dni:
                      type: string
                    name:
                      type: string
                      minLength: 1
                      example: John Doe
                    status:
                      type: string
                      enum:
                        - ACTIVE
                        - PENDING
                        - BLOCKED
                    role:
                      type: string
                      enum:
                        - ADMIN
                        - MENTOR
                        - REGISTERED
                    createdAt:
                      type: string
                      example: 21/02/2024
                    itineraryName:
                      type: string
                      example: Frontend Angular
                    deletedAt:
                      type: string
                      nullable: true
                  required:
                    - id
                    - dni
                    - name
                    - status
                    - role
                    - createdAt
                    - itineraryName
                    - deletedAt
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/dashboard/users/me:
    get:
      tags:
        - dashboard
      operationId: getDashboardMe
      description: Returns information of a logged in user.
      summary: Get user information
      security:
        - cookieAuth: []
      responses:
        "200":
          description: Token is valid and user information is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dni:
                    type: string
                  email:
                    type: string
                    minLength: 1
                    format: email
                    example: user@example.cat
                  role:
                    type: string
                    enum:
                      - ADMIN
                      - MENTOR
                      - REGISTERED
                required:
                  - dni
                  - email
                  - role
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/dashboard/users/{id}:
    delete:
      tags:
        - dashboard
      operationId: deleteDashboardUser
      description: Soft deletes a user
      summary: Delete a user
      security:
        - cookieAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: string
            example: b6z2od3ut12qs0ilem6njgjp
          required: true
      responses:
        "204":
          description: User has been soft deleted
        "401":
          description: Invalid token or missing token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
        "410":
          description: User is already soft deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedUserError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
    patch:
      tags:
        - dashboard
      operationId: patchDashboardUsers
      description: Updates specific fields of a user. Mentors can only update users
        from the same itinerary, can only update registered users, and cannot
        modify the role or status fields. Mentors can update their own
        information except for the role and status fields.
      summary: Update user information
      security:
        - cookieAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: string
            example: b6z2od3ut12qs0ilem6njgjp
          required: true
      requestBody:
        required: true
        description: Updates an existing user. The ID is mandatory, and all other fields
          are optional. Provide only the fields that need to be updated.
        content:
          application/json:
            schema:
              type: object
              properties:
                dni:
                  type: string
                email:
                  type: string
                  minLength: 1
                  format: email
                  example: user@example.cat
                name:
                  type: string
                  minLength: 1
                  example: John Doe
                password:
                  type: string
                  minLength: 8
                role:
                  type: string
                  enum:
                    - ADMIN
                    - MENTOR
                    - REGISTERED
                status:
                  type: string
                  enum:
                    - ACTIVE
                    - PENDING
                    - BLOCKED
                deletedAt:
                  type: string
                  nullable: true
                  format: date-time
                itineraryId:
                  type: string
      responses:
        "204":
          description: User has been updated
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: No valid fields provided for update
                required:
                  - message
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Mentors can only update users from the same itinerary
                required:
                  - message
        "404":
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User not found
                required:
                  - message
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/dashboard/users/:
    delete:
      tags:
        - dashboard
      operationId: deleteDashboardUsers
      description: Soft deletes a collection of users
      summary: Delete a collection of users
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: object
                  properties:
                    ids:
                      type: array
                      items:
                        type: string
                        example: b6z2od3ut12qs0ilem6njgjp
                  required:
                    - ids
              required:
                - body
      responses:
        "204":
          description: Collection of users has been soft deleted
        "401":
          description: Invalid token or missing token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/dashboard/users/status:
    post:
      tags:
        - dashboard
      operationId: postDashboardStatus
      description: Update a collection of users status
      summary: Get list of users name information
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
                    example: b6z2od3ut12qs0ilem6njgjp
                status:
                  type: string
                  enum:
                    - ACTIVE
                    - BLOCKED
              required:
                - ids
                - status
      responses:
        "204":
          description: The user statuses have been updated successfully.
        "401":
          description: Invalid Credentials error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidCredentialsError"
        "404":
          description: Users not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: b6z2od3ut12qs0ilem6njgjp not found
                required:
                  - message
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message