Аутентификация

API аутентифицирует серверы с помощью ключей API организации. Ключ принадлежит организации (а не человеку), имеет набор разрешений и работает ровно в одном режиме: тестовом или рабочем.

Передача ключа

Используйте любой из заголовков:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

Ключи имеют вид bf_live_… или bf_test_…. Отсутствующий ключ даёт 401 (unauthorized); неверно сформированный, отозванный или просроченный ключ тоже даёт 401. Храните ключи на сервере: никогда не передавайте их в браузер или мобильное приложение. Для подписания в браузере вместо этого создайте сессию подписания.

Тестовые и рабочие ключи

	Тестовый (`bf_test_…`)	Рабочий (`bf_live_…`)
Документы	Формируются с водяным знаком `TEST`	Без водяного знака
Электронная почта	Доставляется только участникам вашей организации	Доставляется каждому получателю
Оплата	Бесплатно и без ограничений, никогда не учитывается	Завершённые конверты учитываются в вашем тарифе
Данные	Конверты, ссылки и конечные точки вебхуков, созданные ключом, находятся в тестовом режиме	В рабочем режиме

Режим определяется ключом, а не запросом: ?test_mode=true в POST /v1/envelopes действует только для сессий панели управления. Списки (GET /v1/envelopes, GET /v1/signing-links) возвращают только объекты в режиме ключа, а события конверта отправляются только на конечные точки вебхуков в том же режиме. Каждый конверт и каждая полезная нагрузка вебхука указывают свой режим (testMode).

Создание и отзыв ключей

Ключами управляют в панели управления, в разделе Настройки › Ключи API; это могут делать участники с разрешением apikey:manage (владельцы и администраторы). Секрет показывается один раз — при создании ключа. Ключу можно задать имя, режим, срок действия (от 1 до 365 дней или бессрочно) и области доступа.

Области доступа

Области доступа ключа — это разрешения организации, которые он может использовать. По умолчанию новый ключ получает разрешения создателя, кроме административных (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), и никто не может выдать ключу разрешение, которого нет у него самого. Вызов за пределами областей доступа ключа даёт 403 с указанием недостающего разрешения:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Разрешение	Что позволяет ключу
`template:read`	Получать списки и читать шаблоны, версии и их PDF
`template:write`	Создавать шаблоны, загружать файлы, сохранять черновики, удалять неиспользуемые шаблоны
`template:publish`	Публиковать черновик как новую версию
`envelope:read`	Получать списки и читать конверты, документы и журналы аудита; получать список ссылок для подписания
`envelope:send`	Создавать конверты, сессии подписания и ссылки для подписания; повторно отправлять ссылки
`envelope:void`	Аннулировать конверты в процессе подписания
`org:manage`	Управлять конечными точками вебхуков и повторно доставлять события; читать настройки организации
`billing:manage`	Читать данные об использовании (`GET /v1/usage`) и суммы счетов

Для управления конечными точками вебхуков нужно org:manage, которое ключи по умолчанию не получают: регистрируйте конечные точки в панели управления или явно создайте ключ с этой областью доступа.

Какие учётные данные принимают конечные точки

Для каждой операции в справочнике API указаны её схемы безопасности. Вкратце:

Ключ API или сессия панели управления: шаблоны, конверты, сессии подписания, ссылки для подписания, конечные точки вебхуков, настройки организации, сводка по оплате и использование.
Только сессия панели управления: ключи API, токены SCIM, настройки подключения SSO, загрузка логотипа организации, оформление оплаты и платёжный портал, просмотр секрета вебхука.
Токен подписанта: /v1/signing/*, используется размещённой у нас страницей и <bf-signing> с токеном сессии (bfs_…) или токеном доступа, на который он обменивается (bfa_…).
Публичные: /v1/links/{id} (постоянные ссылки), /v1/sso/discover и API проверки (/v1/public/*, /.well-known/bona-fide/keys.json).

Вход в панель управления

Люди (а не серверы) входят в панель управления по адресу https://app.bonafidesign.com/sign-in. По умолчанию используются адрес электронной почты и пароль; альтернативы — шестизначный код по почте (Отправить мне код), волшебная ссылка, ключ доступа (passkey), Google или Microsoft и корпоративный SSO вашей компании.

При создании учётной записи с паролем отправляется одно письмо: код, подтверждающий, что адрес принадлежит вам. До этого пароль не позволяет войти. Регистрация с адресом, для которого уже есть учётная запись, ничего не меняет и даёт точно такой же ответ, как новая регистрация; владелец адреса получает письмо с объяснением, как войти.
Пароли содержат от 12 до 128 символов и хранятся в виде хешей scrypt с солью. Новый пароль, встречающийся в известной утечке данных, отклоняется: в сервис Have I Been Pwned отправляются только первые пять символов его хеша SHA-1 (k-анонимность), но никогда сам пароль. Если сервис не отвечает в течение двух секунд, пароль принимается без проверки.
Забыли пароль? Письмо для сброса содержит ссылку на страницу, где вы задаёте новый пароль. Ссылка срабатывает один раз, действует один час, а её использование завершает ваши сеансы на всех устройствах.
Пароля ещё нет? Учётные записи, созданные с помощью кода, ссылки, ключа доступа или Google / Microsoft, продолжают входить тем же способом и могут добавить пароль в разделе Настройки › Учётная запись. Для установки первого пароля нужен вход не более 15 минут назад (страница отправит вам код по почте, чтобы подтвердить, что это вы); для смены пароля нужен текущий. В обоих случаях остальные сеансы завершаются.
Ошибки никогда не раскрывают наличие учётных записей: неверный пароль, неизвестный адрес и учётная запись без пароля получают одинаковый ответ, а запрос на сброс всегда сообщает, что письмо уже в пути.
Ограничения частоты: вход по паролю, регистрация и запросы на сброс ограничиваются по IP-адресу и по адресу электронной почты; после превышения лимита ответом будет 429, пока не истечёт окно.
Корпоративный SSO: если ваша организация требует SSO, участники с адресами в её почтовых доменах входят только через поставщика удостоверений. Пароли, коды и волшебные ссылки для них отклоняются; у владельцев остаётся код по почте в качестве аварийного способа входа.

Идентификаторы запросов

Каждый ответ содержит заголовок x-request-id, а каждое тело ошибки — поле requestId. Вы можете передать собственный x-request-id (от 8 до 128 символов из набора A-Z a-z 0-9 . _ -), чтобы сопоставлять журналы; иначе API сгенерирует его сам. Указывайте его при обращении в поддержку.