Control-plane/docs/swagger.yaml

basePath: /api/v1
definitions:
  auth.AuthResponse:
    properties:
      refresh_token:
        example: dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4=
        type: string
      token:
        example: eyJhbGciOiJIUzI1NiIs...
        type: string
      user:
        $ref: '#/definitions/auth.UserPublic'
    type: object
  auth.ErrorResponse:
    properties:
      error:
        example: invalid email or password
        type: string
    type: object
  auth.LoginRequest:
    properties:
      email:
        example: john@example.com
        type: string
      password:
        example: secret123
        type: string
    required:
    - email
    - password
    type: object
  auth.LogoutRequest:
    properties:
      refresh_token:
        example: dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4=
        type: string
    required:
    - refresh_token
    type: object
  auth.PasswordChangeRequest:
    properties:
      new_password:
        example: NewSecret456!
        minLength: 8
        type: string
      old_password:
        example: Secret123!
        type: string
    required:
    - new_password
    - old_password
    type: object
  auth.RefreshRequest:
    properties:
      refresh_token:
        example: dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4=
        type: string
    required:
    - refresh_token
    type: object
  auth.RegisterRequest:
    properties:
      email:
        example: john@example.com
        type: string
      password:
        example: Secret123!
        minLength: 8
        type: string
      username:
        example: john
        maxLength: 30
        minLength: 3
        type: string
    required:
    - email
    - password
    - username
    type: object
  auth.UpdateProfileRequest:
    properties:
      username:
        example: john_updated
        maxLength: 30
        minLength: 3
        type: string
    required:
    - username
    type: object
  auth.UserPublic:
    properties:
      created_at:
        type: string
      email:
        type: string
      id:
        type: string
      username:
        type: string
    type: object
  auth.UserResponse:
    properties:
      user:
        $ref: '#/definitions/auth.UserPublic'
    type: object
  org.CreateOrgRequest:
    properties:
      name:
        example: My Corp
        maxLength: 100
        minLength: 2
        type: string
      slug:
        example: my-corp
        maxLength: 50
        minLength: 2
        type: string
    required:
    - name
    - slug
    type: object
  org.ErrorResponse:
    properties:
      error:
        type: string
    type: object
  org.OrgListResponse:
    properties:
      limit:
        type: integer
      offset:
        type: integer
      organizations:
        items:
          $ref: '#/definitions/org.Organization'
        type: array
      total:
        type: integer
    type: object
  org.OrgResponse:
    properties:
      organization:
        $ref: '#/definitions/org.Organization'
    type: object
  org.Organization:
    properties:
      created_at:
        type: string
      id:
        type: string
      name:
        type: string
      slug:
        type: string
      updated_at:
        type: string
    type: object
  org.UpdateOrgRequest:
    properties:
      name:
        example: My Corp Updated
        maxLength: 100
        minLength: 2
        type: string
    required:
    - name
    type: object
info:
  contact: {}
  description: |-
    API системы управления AegisGuard. Позволяет управлять пользователями и организациями.
    Все защищённые эндпоинты требуют заголовок `Authorization: Bearer <token>`.
    Токен получается при регистрации или входе.
  title: AegisGuard API
  version: "1.0"
paths:
  /api/v1/auth/login:
    post:
      consumes:
      - application/json
      description: Аутентификация по email и паролю. Возвращает access_token (JWT)
        и refresh_token.
      parameters:
      - description: Email и пароль
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/auth.LoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Успешный вход, токены в ответе
          schema:
            $ref: '#/definitions/auth.AuthResponse'
        "400":
          description: Ошибка валидации полей
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
        "401":
          description: Неверный email или пароль
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
      summary: Вход
      tags:
      - auth
  /api/v1/auth/logout:
    post:
      consumes:
      - application/json
      description: Аннулирование refresh_token. После выхода повторное использование
        того же refresh_token вернёт 401.
      parameters:
      - description: Refresh_token для аннулирования
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/auth.LogoutRequest'
      produces:
      - application/json
      responses:
        "200":
          description: '{"message": "logged out successfully"}'
          schema:
            additionalProperties:
              type: string
            type: object
        "400":
          description: Не указан refresh_token
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
        "401":
          description: Refresh_token не найден или уже аннулирован
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
      summary: Выход
      tags:
      - auth
  /api/v1/auth/me:
    get:
      consumes:
      - application/json
      description: |-
        Получение профиля текущего авторизованного пользователя.
        **Требуется:** заголовок `Authorization: Bearer <token>`.
      produces:
      - application/json
      responses:
        "200":
          description: Данные пользователя
          schema:
            $ref: '#/definitions/auth.UserResponse'
        "401":
          description: Токен не указан или недействителен
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
      security:
      - Bearer: []
      summary: Профиль пользователя
      tags:
      - auth
    put:
      consumes:
      - application/json
      description: |-
        Обновление username текущего пользователя.
        **Требуется:** заголовок `Authorization: Bearer <token>`.
      parameters:
      - description: Новый username
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/auth.UpdateProfileRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Обновлённый профиль
          schema:
            $ref: '#/definitions/auth.UserResponse'
        "400":
          description: 'Ошибка валидации: username от 3 до 30 символов'
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
        "401":
          description: Токен не указан или недействителен
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
      security:
      - Bearer: []
      summary: Обновление профиля
      tags:
      - auth
  /api/v1/auth/password:
    put:
      consumes:
      - application/json
      description: |-
        Изменение пароля текущего пользователя. Требуется указать старый и новый пароль.
        **Требуется:** заголовок `Authorization: Bearer <token>`.
        Пароль должен содержать минимум 8 символов, заглавную букву, строчную букву и цифру.
      parameters:
      - description: Старый и новый пароль
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/auth.PasswordChangeRequest'
      produces:
      - application/json
      responses:
        "200":
          description: '{"message": "password changed successfully"}'
          schema:
            additionalProperties:
              type: string
            type: object
        "400":
          description: 'Ошибка валидации: неверный старый пароль, слабый новый или
            совпадают'
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
        "401":
          description: Токен не указан или недействителен
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
      security:
      - Bearer: []
      summary: Смена пароля
      tags:
      - auth
  /api/v1/auth/refresh:
    post:
      consumes:
      - application/json
      description: |-
        Получение новой пары токенов по refresh_token. Старый refresh_token становится недействительным (ротация).
        Если refresh_token истёк или уже был использован — придёт 401.
      parameters:
      - description: Действительный refresh_token
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/auth.RefreshRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Новая пара токенов
          schema:
            $ref: '#/definitions/auth.AuthResponse'
        "400":
          description: Не указан refresh_token
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
        "401":
          description: Refresh_token недействителен или истёк
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
      summary: Обновление токенов
      tags:
      - auth
  /api/v1/auth/register:
    post:
      consumes:
      - application/json
      description: |-
        Создание новой учётной записи. После успешной регистрации сразу возвращается access_token и refresh_token.
        Пароль должен содержать минимум 8 символов, заглавную букву, строчную букву и цифру.
      parameters:
      - description: Данные для регистрации
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/auth.RegisterRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Пользователь создан, токены в ответе
          schema:
            $ref: '#/definitions/auth.AuthResponse'
        "400":
          description: Ошибка валидации полей (некорректный email, слабый пароль)
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
        "409":
          description: Email уже зарегистрирован
          schema:
            $ref: '#/definitions/auth.ErrorResponse'
      summary: Регистрация
      tags:
      - auth
  /api/v1/organizations:
    get:
      consumes:
      - application/json
      description: |-
        Получение списка всех организаций с пагинацией.
        **Требуется:** заголовок `Authorization: Bearer <token>`.
      parameters:
      - description: Количество записей на странице (по умолчанию 20)
        in: query
        name: limit
        type: integer
      - description: Смещение от начала списка (по умолчанию 0)
        in: query
        name: offset
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Список организаций
          schema:
            $ref: '#/definitions/org.OrgListResponse'
        "500":
          description: Внутренняя ошибка сервера
          schema:
            $ref: '#/definitions/org.ErrorResponse'
      security:
      - Bearer: []
      summary: Список организаций
      tags:
      - organizations
    post:
      consumes:
      - application/json
      description: |-
        Создание новой организации. slug используется в URL и должен быть уникальным.
        **Требуется:** заголовок `Authorization: Bearer <token>`.
      parameters:
      - description: Название и slug организации
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/org.CreateOrgRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Организация создана
          schema:
            $ref: '#/definitions/org.OrgResponse'
        "400":
          description: Ошибка валидации полей
          schema:
            $ref: '#/definitions/org.ErrorResponse'
        "409":
          description: Slug уже занят
          schema:
            $ref: '#/definitions/org.ErrorResponse'
      security:
      - Bearer: []
      summary: Создание организации
      tags:
      - organizations
  /api/v1/organizations/{id}:
    delete:
      consumes:
      - application/json
      description: |-
        Безвозвратное удаление организации по её ID.
        **Требуется:** заголовок `Authorization: Bearer <token>`.
      parameters:
      - description: UUID организации
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: '{"message": "organization deleted"}'
          schema:
            additionalProperties:
              type: string
            type: object
        "404":
          description: Организация не найдена
          schema:
            $ref: '#/definitions/org.ErrorResponse'
      security:
      - Bearer: []
      summary: Удаление организации
      tags:
      - organizations
    get:
      consumes:
      - application/json
      description: |-
        Получение информации об организации по её ID.
        **Требуется:** заголовок `Authorization: Bearer <token>`.
      parameters:
      - description: UUID организации
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Данные организации
          schema:
            $ref: '#/definitions/org.OrgResponse'
        "404":
          description: Организация не найдена
          schema:
            $ref: '#/definitions/org.ErrorResponse'
      security:
      - Bearer: []
      summary: Получить организацию
      tags:
      - organizations
    put:
      consumes:
      - application/json
      description: |-
        Обновление названия организации. slug изменить нельзя.
        **Требуется:** заголовок `Authorization: Bearer <token>`.
      parameters:
      - description: UUID организации
        in: path
        name: id
        required: true
        type: string
      - description: Новое название организации
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/org.UpdateOrgRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Обновлённая организация
          schema:
            $ref: '#/definitions/org.OrgResponse'
        "400":
          description: Ошибка валидации полей
          schema:
            $ref: '#/definitions/org.ErrorResponse'
        "404":
          description: Организация не найдена
          schema:
            $ref: '#/definitions/org.ErrorResponse'
      security:
      - Bearer: []
      summary: Обновление организации
      tags:
      - organizations
schemes:
- http
securityDefinitions:
  Bearer:
    description: Введите `Bearer <token>`, где token — access_token из ответа /auth/login
      или /auth/register
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"