1KOMMA5° Admin - Users API

openapi: 3.2.0
info:
  title: Offer Tool Admin - Users API
  description: Api definitions for Offer Tool
  version: '1.0'
  contact: {}
tags:
- name: Admin - Users
paths:
  /api/v1/admin/users:
    get:
      operationId: GetAdminUsersController_getAdminUsers_v1
      parameters:
      - name: page
        required: false
        in: query
        description: Page number (1-based)
        schema:
          minimum: 1
          default: 1
          type: number
      - name: limit
        required: false
        in: query
        description: Number of items per page
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: search
        required: false
        in: query
        description: Search by name or email
        schema:
          example: john
          type: string
      - name: tenantIds
        required: false
        in: query
        description: Filter by tenant IDs (comma-separated)
        schema:
          example: tenant-1,tenant-2
          type: array
          items:
            type: string
      - name: countryId
        required: false
        in: query
        description: Filter by country ID
        schema:
          example: 1
          type: number
      - name: sortBy
        required: false
        in: query
        description: Field to sort by
        schema:
          $ref: '#/components/schemas/AdminUserSortField'
      - name: sortOrder
        required: false
        in: query
        description: Sort order
        schema:
          $ref: '#/components/schemas/SortOrder'
      responses:
        '200':
          description: Paginated list of team users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAdminUsersResponseDto'
      summary: Get paginated team users with filtering and sorting
      tags:
      - Admin - Users
    post:
      operationId: CreateAdminUserController_createAdminUser_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdminUserDto'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminUserDetailResponseDto'
        '409':
          description: Email already exists
      summary: Create a new team user
      tags:
      - Admin - Users
  /api/v1/admin/users/me:
    get:
      operationId: GetCurrentAdminUserController_getCurrentAdminUser_v1
      parameters: []
      responses:
        '200':
          description: Current admin user access level info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentAdminUserResponseDto'
      summary: Get current admin user access level info
      tags:
      - Admin - Users
  /api/v1/admin/users/me/branches:
    get:
      description: 'Returns branches based on access level: GLOBAL users get all branches, COUNTRY users
        get branches in their country, BRANCH users get their assigned branches.'
      operationId: GetMyBranchesController_getMyBranches_v1
      parameters: []
      responses:
        '200':
          description: List of accessible branches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyBranchesResponseDto'
      summary: Get branches accessible to the current user
      tags:
      - Admin - Users
  /api/v1/admin/users/assignable-branches:
    get:
      description: Returns branches that the current user can assign to other users. Used in user creation/edit
        forms for branch selection.
      operationId: GetAssignableBranchesController_getAssignableBranches_v1
      parameters:
      - name: countryId
        required: true
        in: query
        schema:
          type: number
      responses:
        '200':
          description: List of branches in the specified country
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AdminBranchDto'
      summary: Get branches assignable to users for a given country
      tags:
      - Admin - Users
  /api/v1/admin/users/{id}:
    get:
      operationId: GetAdminUserController_getAdminUser_v1
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminUserDetailResponseDto'
        '404':
          description: User not found
      summary: Get a single team user by ID
      tags:
      - Admin - Users
    patch:
      operationId: UpdateAdminUserController_updateAdminUser_v1
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAdminUserDto'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminUserDetailResponseDto'
        '404':
          description: User not found
        '409':
          description: Email already exists
      summary: Update a team user
      tags:
      - Admin - Users
  /api/v1/admin/users/{id}/resend-invitation:
    post:
      description: Sends a password setup email to the user. If the user does not exist in Auth0, they
        will be created first.
      operationId: ResendInvitationController_resendInvitation_v1
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: Invitation email sent successfully
        '400':
          description: Auth0 not configured or failed to send email
        '404':
          description: User not found
      summary: Resend invitation email to a user
      tags:
      - Admin - Users
components:
  schemas:
    AdminBranchCountryDto:
      type: object
      properties:
        id:
          type: number
          description: Country ID
          example: 1
        name:
          type: string
          description: Country name
          example: Germany
        countryCode:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          example: DE
      required:
      - id
      - name
      - countryCode
    UpdateAdminUserDto:
      type: object
      properties:
        email:
          type: string
          description: User email address
          example: john.doe@example.com
        name:
          type: string
          description: User full name
          example: John Doe
        accessLevel:
          type: string
          description: Access level determining the scope of data the user can access
          example: branch
          enum:
          - global
          - country
          - branch
        countryId:
          type:
          - object
          - 'null'
          description: Country ID. Required for COUNTRY and BRANCH access levels.
          example: 1
        zohoUserId:
          type:
          - object
          - 'null'
          description: Zoho User ID (can be null to clear)
          example: '12345678901234567'
        tenantIds:
          description: List of tenant/branch IDs to assign to the user
          example:
          - tenant-1
          - tenant-2
          type: array
          items:
            type: array
        defaultTenantId:
          type:
          - object
          - 'null'
          description: Default tenant/branch ID (can be null for central users to clear)
          example: tenant-1
        roles:
          description: Role names to assign to the user (replaces existing roles)
          example:
          - sales
          - branch lead
          type: array
          items:
            type: array
    PaginationMetaDto:
      type: object
      properties:
        total:
          type: number
          description: Total number of items
          example: 100
        page:
          type: number
          description: Current page number
          example: 1
        limit:
          type: number
          description: Number of items per page
          example: 20
        totalPages:
          type: number
          description: Total number of pages
          example: 5
      required:
      - total
      - page
      - limit
      - totalPages
    AdminUserTenantDto:
      type: object
      properties:
        id:
          type: string
          description: Tenant ID
          example: tenant-1
        name:
          type: string
          description: Tenant name (branch name)
          example: Berlin Branch
      required:
      - id
      - name
    CurrentAdminUserResponseDto:
      type: object
      properties:
        id:
          type: number
          description: User ID
          example: 123
        accessLevel:
          description: Access level determining the scope of data the user can access
          example: branch
          allOf:
          - $ref: '#/components/schemas/AccessLevel'
        countryId:
          type:
          - object
          - 'null'
          description: Country ID (null for GLOBAL users)
          example: 1
        countryName:
          type:
          - object
          - 'null'
          description: Country name (null for GLOBAL users)
          example: Germany
        tenants:
          description: List of tenants the user has access to (for BRANCH level users)
          items:
            type: array
          type: array
      required:
      - id
      - accessLevel
      - countryId
      - countryName
      - tenants
    AdminUserDetailResponseDto:
      type: object
      properties:
        id:
          type: number
          description: Unique identifier of the user
          example: 123
        email:
          type: string
          description: User email address
          example: john.doe@example.com
        name:
          type: string
          description: User full name
          example: John Doe
        accessLevel:
          description: Access level determining the scope of data the user can access
          example: branch
          allOf:
          - $ref: '#/components/schemas/AccessLevel'
        countryId:
          type:
          - object
          - 'null'
          description: Country ID
          example: 1
        zohoUserId:
          type:
          - object
          - 'null'
          description: Zoho User ID
          example: '12345678901234567'
        defaultTenantId:
          type:
          - object
          - 'null'
          description: Default tenant/branch ID
          example: tenant-1
        createdAt:
          type: string
          description: Timestamp when the user was created
          example: '2024-01-15T10:30:00.000Z'
        tenants:
          description: Tenants (branches) the user belongs to
          type: array
          items:
            $ref: '#/components/schemas/AdminUserTenantDto'
        hiddenBranchCount:
          type: number
          description: Number of branches the user has access to that the current user cannot see or modify
          example: 0
        roles:
          description: Role names assigned to the user
          example:
          - sales
          - branch lead
          type: array
          items:
            type: array
      required:
      - id
      - email
      - name
      - accessLevel
      - countryId
      - zohoUserId
      - defaultTenantId
      - createdAt
      - tenants
      - hiddenBranchCount
      - roles
    AdminUserResponseDto:
      type: object
      properties:
        id:
          type: number
          description: Unique identifier of the user
          example: 123
        email:
          type: string
          description: User email address
          example: john.doe@example.com
        name:
          type: string
          description: User full name
          example: John Doe
        accessLevel:
          description: Access level determining the scope of data the user can access
          example: branch
          allOf:
          - $ref: '#/components/schemas/AccessLevel'
        createdAt:
          type: string
          description: Timestamp when the user was created
          example: '2024-01-15T10:30:00.000Z'
        lastLoginAt:
          type:
          - object
          - 'null'
          description: Timestamp of last login
          example: '2024-06-20T14:45:00.000Z'
        tenants:
          description: Tenants (branches) the user belongs to
          type: array
          items:
            $ref: '#/components/schemas/AdminUserTenantDto'
      required:
      - id
      - email
      - name
      - accessLevel
      - createdAt
      - lastLoginAt
      - tenants
    MyBranchesResponseDto:
      type: object
      properties:
        branches:
          description: List of branches accessible to the current user
          items:
            type: array
          type: array
      required:
      - branches
    AdminUserSortField:
      type: string
      enum:
      - createdAt
      - name
      - email
      - lastLoginAt
    AdminBranchDto:
      type: object
      properties:
        id:
          type: string
          description: Branch ID
          example: branch-123
        name:
          type: string
          description: Branch name
          example: Berlin Branch
        zohoId:
          type:
          - object
          - 'null'
          description: Zoho CRM ID
          example: '12345678'
        country:
          description: Country information
          allOf:
          - $ref: '#/components/schemas/AdminBranchCountryDto'
      required:
      - id
      - name
      - zohoId
      - country
    PaginatedAdminUsersResponseDto:
      type: object
      properties:
        data:
          description: Array of user entries
          type: array
          items:
            $ref: '#/components/schemas/AdminUserResponseDto'
        meta:
          description: Pagination metadata
          allOf:
          - $ref: '#/components/schemas/PaginationMetaDto'
      required:
      - data
      - meta
    AccessLevel:
      type: string
      enum:
      - global
      - country
      - branch
    SortOrder:
      type: string
      enum:
      - asc
      - desc
    CreateAdminUserDto:
      type: object
      properties:
        email:
          type: string
          description: User email address
          example: john.doe@example.com
        name:
          type: string
          description: User full name
          example: John Doe
        accessLevel:
          description: Access level determining the scope of data the user can access
          example: branch
          allOf:
          - $ref: '#/components/schemas/AccessLevel'
        countryId:
          type:
          - object
          - 'null'
          description: Country ID. Required for COUNTRY and BRANCH access levels.
          example: 1
        zohoUserId:
          type: string
          description: Zoho User ID
          example: '12345678901234567'
        tenantIds:
          description: List of tenant/branch IDs to assign to the user
          example:
          - tenant-1
          - tenant-2
          type: array
          items:
            type: array
        defaultTenantId:
          type:
          - object
          - 'null'
          description: Default tenant/branch ID. Central users can leave this null.
          example: tenant-1
        roles:
          description: Role names to assign to the user
          example:
          - sales
          - branch lead
          type: array
          items:
            type: array
      required:
      - email
      - name
      - accessLevel
servers:
- url: https://heartbeat.1komma5grad.com
  description: Base URL reconciled from apis.yml