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

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

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

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

Подробное описание всех доступных API-эндпоинтов — в интерактивном просмотрщике схемы API: операции, параметры, схемы запросов и ответов, сравнение версий и примеры для cURL, Python и passwork-cli.

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

Одной из ключевых особенностей 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. Обычно используется эндпоинт POST /api/v1/sessions/refresh с заголовком Authorization: Bearer и телом с refreshToken для получения новой пары токенов. Для API-сессий (в т.ч. сервисных аккаунтов) дополнительно доступны отдельные маршруты: обновить только access или только refresh — ротация API-токенов;
4. Автоматическое обновление: Python коннектор автоматически обрабатывает истечение срока действия токена и выполняет обновление без вмешательства пользователя;
5. Сохранение сессии: Python коннектор позволяет сохранять и восстанавливать сессии, что удобно для долгосрочной автоматизации. Сохраненные сессии шифруются для безопасности.

Формат ответа API

Заголовок запроса X-Response-Format задаёт формат ответа от API:

• base64 — ответ от сервера возвращается в кодировке Base64 (значение по умолчанию);
• raw — ответ возвращается в JSON формате.

Добавьте в запрос заголовок X-Response-Format: raw, чтобы получать ответ в JSON. Для ответа в base64 используйте X-Response-Format: base64 или не указывайте заголовок.

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

При использовании 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

Публичные ссылки (Links)

• Создание ссылки: 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
• Обновление только access (API-сессии): POST /api/v1/sessions/refresh-access-token
• Обновление только refresh (API-сессии): POST /api/v1/sessions/refresh-refresh-token

Настройки (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

Версия для LLM