Перейти к основному содержимому
Passwork LogoPasswork Logo
search
7.0arrow
Версия: 7.0

Описание и основные возможности API​

API Пассворка предоставляет программный интерфейс для взаимодействия с сервисом управления паролями Пассворк. API позволяет автоматизировать операции с паролями, хранилищами, пользователями и другими объектами системы, обеспечивая полный программный контроль над всеми аспектами работы с Пассворком.

Наше API предоставляет следующие возможности:

  • Управление паролями: создание, получение, обновление, удаление паролей;
  • Управление хранилищами (Vaults): создание новых хранилищ, управление доступом;
  • Управление папками: создание структуры папок внутри хранилищ;
  • Управление пользователями: создание пользователей, настройка прав доступа;
  • Управление группами пользователей: объединение пользователей в группы для упрощения управления доступом;
  • Общий доступ к паролям: предоставление другим пользователям доступа к паролям через механизм Inbox;
  • Создание публичных ссылок: временный доступ к паролям через ссылки;
  • Поддержка вложений: работа с прикрепленными к паролям файлами;
  • Поиск и фильтрация: поиск паролей по различным критериям;
  • Управление ярлыками: создание ссылок на пароли в других хранилищах;
  • Работа с корзиной: восстановление удаленных объектов;
  • Журналирование активности: получение информации о действиях пользователей.

При установке Пассворка в комплекте с .zip-архивом также поставляется Api reference.pdf, содержащий подробное описание всех доступных API-эндпоинтов:

/<passwork>/www/latest/files/api-schema/Api reference.pdf

Клиентское шифрование​

Одной из ключевых особенностей API Пассворка является поддержка клиентского шифрования. При использовании клиентского шифрования все критически важные данные (пароли, конфиденциальные поля, вложения) шифруются на стороне клиента перед отправкой на сервер.

Принцип работы криптографии​

  1. Мастер-пароль: Для шифрования используется мастер-пароль, который знает только пользователь. Мастер-пароль никогда не передается на сервер;
  2. Мастер-ключ: На основе мастер-пароля с использованием PBKDF2 (Password-Based Key Derivation Function 2) генерируется мастер-ключ;
  3. Хеш мастер-ключа: Рассчитывается хеш мастер-ключа с использованием SHA-256. Этот хеш передается на сервер для подтверждения подлинности клиента;
  4. Ключи сейфов: Для каждого хранилища генерируется уникальный ключ, который используется для шифрования паролей и других данных в этом хранилище;
  5. Асимметричное шифрование: Для обмена ключами между пользователями используется асимметричное шифрование (RSA). У каждого пользователя есть пара ключей - публичный и приватный;
  6. Шифрование данных: Для шифрования паролей и других конфиденциальных данных используется симметричное шифрование AES в режиме CBC с PKCS7-паддингом.

Ответственность клиента API​

осторожно

Важно: В соответствии с архитектурой Zero Knowledge, API Пассворка предполагает реализацию криптографических операций на стороне клиента. Это означает, что шифрование и дешифрование данных должно выполняться в клиентском приложении до отправки на сервер. Серверная часть Пассворка работает с уже зашифрованными данными и дополнительно применяет свой собственный уровень шифрования, создавая многослойную защиту.

Клиент API должен обеспечивать:

  • Генерацию и хранение мастер-ключа на основе мастер-пароля;
  • Шифрование данных перед отправкой на сервер;
  • Дешифрование данных, полученных с сервера;
  • Вычисление хеша мастер-ключа для авторизации;
  • Асимметричное шифрование ключей при обмене с другими пользователями.

Python коннектор​

Для упрощения работы с API и реализации всех необходимых криптографических операций, Пассворк предоставляет официальный Python-коннектор. Коннектор инкапсулирует всю сложность работы с криптографией и API в простой программный интерфейс.

Python коннектор обеспечивает:

  • Управление сессиями и авторизацией;
  • Автоматическое продление сессии по refreshToken;
  • Криптографические операции (шифрование/расшифрование);
  • Готовые методы для основных операций с API;
  • Универсальный метод call() для произвольных запросов к API.

Авторизация и работа с сессиями​

Авторизация​

Процесс авторизации выглядит следующим образом:

  1. Пользователь Пассворка на вкладке Авторизация и 2ФА в разделе API-токены нажимает Сгененировать пару;
  2. Сервер возвращает пару токенов: accessToken и refreshToken;
  3. Пользователь использует accessToken для всех последующих запросов, добавляя его в заголовок Authorization: Bearer {accessToken};
  4. Если включено клиентское шифрование, пользователь также получает Passwork-MasterKeyHash и добавляет его в заголовок.

Работа с сессией и refreshToken​

API Пассворка использует механизм токенов доступа с ограниченным сроком действия:

  1. Access Token: Основной токен для авторизации запросов. Имеет ограниченный срок действия (обычно несколько минут или часов);
  2. Refresh Token: Долгоживущий токен, используемый для получения нового access token без повторной аутентификации;
  3. Обновление токена: Когда access token истекает, клиент получает ошибку 401 с кодом accessTokenExpired. В этом случае клиент должен отправить запрос на эндпоинт /api/v1/sessions/refresh с текущим refresh token для получения новой пары токенов;
  4. Автоматическое обновление: Python коннектор автоматически обрабатывает истечение срока действия токена и выполняет обновление без вмешательства пользователя;
  5. Сохранение сессии: Python коннектор позволяет сохранять и восстанавливать сессии, что удобно для долгосрочной автоматизации. Сохраненные сессии шифруются для безопасности.

Рекомендации по безопасности​

При использовании API Пассворка следует соблюдать следующие рекомендации по безопасности:

  1. Защита API ключей: Храните API ключи в безопасном месте, используйте переменные окружения или защищенные хранилища секретов;
  2. Ротация ключей: Регулярно обновляйте API ключи для минимизации рисков;
  3. HTTPS: Используйте только HTTPS для всех коммуникаций с API;
  4. Минимальные привилегии: Создавайте отдельных пользователей для API с минимально необходимыми правами доступа;
  5. Защита мастер-пароля: Храните мастер-пароль с максимальной защитой, так как компрометация мастер-пароля приведет к компрометации всех паролей;
  6. Защита сохраненных сессий: Обеспечьте надежную защиту сохраненных сессий и ключей шифрования;
  7. Обработка ошибок: Внимательно обрабатывайте ошибки API, не раскрывая чувствительную информацию в логах.

Основные эндпоинты и возможности API​

Хранилища (Vaults)​

  • Создание хранилища: POST /api/v1/vaults
  • Получение списка хранилищ: GET /api/v1/vaults
  • Получение информации о хранилище: GET /api/v1/vaults/{id}
  • Обновление хранилища: POST /api/v1/vaults/{id}
  • Удаление хранилища: DELETE /api/v1/vaults/{id}
  • Управление доступом пользователей:
    • POST /api/v1/vaults/{id}/grant-user-access
    • POST /api/v1/vaults/{id}/revoke-user-access
  • Управление доступом групп:
    • POST /api/v1/vaults/{id}/grant-user-group-access
    • POST /api/v1/vaults/{id}/revoke-user-group-access
  • Импорт хранилищ: POST /api/v1/vaults/import

Папки (Folders)​

  • Создание папки: POST /api/v1/folders
  • Получение списка папок: GET /api/v1/folders
  • Получение информации о папке: GET /api/v1/folders/{id}
  • Обновление папки: POST /api/v1/folders/{id}
  • Удаление папки: DELETE /api/v1/folders/{id}
  • Копирование папки: POST /api/v1/folders/{id}/copy
  • Перемещение папки: POST /api/v1/folders/{id}/move
  • Управление доступом:
    • POST /api/v1/folders/{id}/grant-user-access
    • POST /api/v1/folders/{id}/revoke-user-access
  • Импорт/экспорт папок:
    • POST /api/v1/folders/import
    • POST /api/v1/directories/export

Элементы/Пароли (Items)​

  • Создание пароля: POST /api/v1/items
  • Получение списка паролей: GET /api/v1/items
  • Получение информации о пароле: GET /api/v1/items/{id}
  • Обновление пароля: PATCH /api/v1/items/{id}
  • Удаление пароля: DELETE /api/v1/items/{id}
  • Копирование пароля: POST /api/v1/items/{id}/copy
  • Перемещение пароля: POST /api/v1/items/{id}/move
  • Получение вложений: GET /api/v1/items/{id}/attachment/{attachmentId}
  • Массовые операции:
    • POST /api/v1/items/copy/bulk
    • POST /api/v1/items/move/bulk
    • POST /api/v1/items/delete/bulk
  • Импорт/экспорт паролей:
    • POST /api/v1/items/import
    • POST /api/v1/items/export
  • Поиск паролей: GET /api/v1/items/search
  • Анализ безопасности: GET /api/v1/items/security-analysis

Пользователи (Users)​

  • Создание пользователя: POST /api/v1/users
  • Получение списка пользователей: GET /api/v1/users
  • Получение информации о пользователе: GET /api/v1/users/{id}
  • Обновление пользователя: PATCH /api/v1/users/{id}
  • Удаление пользователя: DELETE /api/v1/users/{id}
  • Блокировка/разблокировка пользователя:
    • POST /api/v1/users/{id}/block
    • POST /api/v1/users/{id}/unblock
  • Двухфакторная аутентификация:
    • POST /api/v1/users/2fa/set-up
    • POST /api/v1/users/2fa/set-state
    • POST /api/v1/users/2fa/reset

Группы пользователей (User Groups)​

  • Создание группы: POST /api/v1/user-groups
  • Получение списка групп: GET /api/v1/user-groups
  • Получение информации о группе: GET /api/v1/user-groups/{id}
  • Обновление группы: POST /api/v1/user-groups/{id}
  • Удаление группы: DELETE /api/v1/user-groups/{id}
  • Управление участниками группы:
    • POST /api/v1/user-groups/{id}/add-users
    • POST /api/v1/user-groups/{id}/remove-users
  • Массовые операции с группами:
    • POST /api/v1/user-groups/delete/bulk
    • POST /api/v1/user-groups/set-state/bulk

Роли пользователей (User Roles)​

  • Создание роли: POST /api/v1/user-roles
  • Получение списка ролей: GET /api/v1/user-roles
  • Получение информации о роли: GET /api/v1/user-roles/{id}
  • Обновление роли: PATCH /api/v1/user-roles/{id}
  • Удаление роли: DELETE /api/v1/user-roles/{id}
  • Управление разрешениями: GET /api/v1/user-roles/permission-items/list

Общий доступ (Inbox Items)​

  • Отправка пароля пользователю: POST /api/v1/inbox-items/send-to-user
  • Отправка пароля группе пользователей: POST /api/v1/inbox-items/send-to-user-group
  • Получение списка входящих паролей: GET /api/v1/inbox-items
  • Поиск входящего пароля: GET /api/v1/inbox-items/search
  • Получение входящего пароля: GET /api/v1/inbox-items/{id}
  • Установка типа доступа: POST /api/v1/inbox-items/{id}/set-access
  • Массовое удаление: POST /api/v1/inbox-items/delete/bulk
  • Создание ссылки: POST /api/v1/links
  • Получение списка ссылок:
    • GET /api/v1/links/folder/{folderId}
    • GET /api/v1/links/item/{itemId}
    • GET /api/v1/links/vault/{vaultId}
  • Удаление ссылки: DELETE /api/v1/links/{id}
  • Массовое удаление: POST /api/v1/links/delete/bulk

Корзина (Bin Items)​

  • Получение списка элементов в корзине: GET /api/v1/bin-items
  • Получение элемента корзины:
    • GET /api/v1/bin-items/{id}/folder
    • GET /api/v1/bin-items/{id}/item
    • GET /api/v1/bin-items/{id}/shortcut
  • Восстановление элементов:
    • POST /api/v1/bin-items/restore/bulk
    • POST /api/v1/bin-items/restore-and-move/bulk
  • Удаление элементов:
    • DELETE /api/v1/bin-items/{id}
    • POST /api/v1/bin-items/delete/bulk
    • DELETE /api/v1/bin-items/all

Ярлыки (Shortcuts)​

  • Создание ярлыка: POST /api/v1/shortcuts
  • Получение списка ярлыков: GET /api/v1/shortcuts
  • Получение информации о ярлыке: GET /api/v1/shortcuts/{id}
  • Копирование ярлыка: POST /api/v1/shortcuts/{id}/copy
  • Перемещение ярлыка: POST /api/v1/shortcuts/move/bulk
  • Удаление ярлыка: DELETE /api/v1/shortcuts/{id}
  • Массовые операции:
    • POST /api/v1/shortcuts/create/bulk
    • POST /api/v1/shortcuts/copy/bulk
    • POST /api/v1/shortcuts/move/bulk
    • POST /api/v1/shortcuts/delete/bulk

Журналы активности (Activity Logs)​

  • Получение журналов: GET /api/v1/activity-logs
  • Получение информации о событии: GET /api/v1/activity-logs/{id}
  • Получение последних действий пользователей: GET /api/v1/activity-logs/directories/last-users-activities
  • Получение последних действий пользователя: GET /api/v1/activity-logs/user/latest

Сессии (Sessions)​

  • Получение информации о текущей сессии: GET /api/v1/sessions/current/info
  • Получение списка сессий: GET /api/v1/sessions
  • Удаление сессии: DELETE /api/v1/sessions/{id}
  • Обновление токена: POST /api/v1/sessions/refresh

Настройки (Settings)​

  • Получение/обновление настроек:
    • Пароли: GET/PATCH /api/v1/settings/auth-password-complexity
    • Мастер-пароли: GET/PATCH /api/v1/settings/master-password-complexity
    • Интерфейс: GET/PATCH /api/v1/settings/interface
    • Сессии: GET/PATCH /api/v1/settings/session
    • Уведомления: GET/PATCH /api/v1/settings/notifications
    • Журналы активности: GET/PATCH /api/v1/settings/activity-log
    • Поиск: GET/PATCH /api/v1/settings/search
    • Хранилища: GET/PATCH /api/v1/settings/vault
    • Пользователи: GET/PATCH /api/v1/settings/user

Приглашения пользователей (User Invites)​

  • Создание приглашения: POST /api/v1/user-invites
  • Получение списка приглашений: GET /api/v1/user-invites
  • Получение информации о приглашении: GET /api/v1/user-invites/{id}
  • Удаление приглашения: DELETE /api/v1/user-invites/{id}
  • Создание и отправка приглашения: POST /api/v1/user-invites/create-and-send
© 2014–2025 ООО «Пассворк»