Авторизация

Все запросы к BCS API авторизуются Bearer-токеном. Один токен = одна компания + конкретный набор расчётных счетов + ограниченные права.

Формат токена

Токен — непрозрачная строка с префиксом, который указывает на окружение:

bcs_live_<random> — production окружение
bcs_test_<random> — dev / staging

В БД хранится только sha256(token) + видимая часть (token_prefix, первые 25 символов). Полное значение показывается один раз в момент выпуска. Если потеряли — выпустить новый и отозвать старый.

Заголовок Authorization

Authorization: Bearer bcs_live_xxxxxxxxxxxxxxxxxxxxxx

Других схем авторизации (Basic, Cookies, query-param) нет и не планируется. Один запрос — один токен.

В логах приложения токен не должен появляться целиком. Для корреляции достаточно token_prefix — он безопасен для логирования и совпадает с тем, что показывается в admin UI.

Два назначения токена (purpose)

integration — для M2M-интеграций

Для ERP, 1С, кастомных backend-сервисов. Поддерживает оба глобальных scope: read_statements и send_payments. Эндпоинты доступа: /api/v1/integration/*.

mcp — для AI-ассистентов

Для подключения Claude Code, Claude Desktop, Cursor через MCP (Model Context Protocol). Read-only по дизайну: scope send_payments запрещён на уровне backend-валидации — admin API не пропускает scope_send_payments=true для purpose=mcp даже через прямой POST. Эндпоинты доступа: /api/v1/mcp (Streamable HTTP, рекомендуется) и /api/v1/mcp/* (REST для stdio-бинарника bcs-mcp). Подробности — MCP.

:::warning Использование интеграционного токена в endpoint'е MCP (или наоборот) → 403 forbidden_purpose в auth-middleware ещё до handler'а. :::

Глобальные scopes

Поле	Тип	Описание
`read_statements`	bool	Позволяет вызывать `/integration/statements/*`, `/integration/bank-accounts`, а для MCP-токена — все 6 read-only tools.
`send_payments`	bool	Позволяет вызывать `/integration/payments/*` (upload, submit, item-submit). Доступен только для `purpose=integration`.

Глобальный scope — необходимое, но не достаточное условие. Поверх него работает per-account ACL (см. ниже).

Account-level ACL

Каждый токен привязан к одной компании; внутри компании — к заранее выбранному набору расчётных счетов. Для каждого РС хранятся per-account флаги:

Поле	Тип	Описание
`allow_read_statements`	bool	Разрешает токену видеть РС в `GET /integration/bank-accounts` и заказывать выписки.
`allow_send_payments`	bool	Разрешает submit платежей на этот РС. Только если глобальный scope `send_payments=true`.

:::info Защита от неожиданного расширения доступа Новый РС в компании не подключается автоматически к существующим токенам. Каждое добавление РС в ACL — явное действие администратора. Это сознательно: внешний сервис не получает доступ к данным, которые не были согласованы. :::

Дополнительные параметры безопасности

Поле	Тип	Описание
`allowed_ips`	string[]	Список IP-адресов или CIDR-блоков. Запрос с IP вне списка → `403 forbidden_ip`. Пустой список = без IP-фильтра. На production задавайте всегда.
`rate_limit_per_minute`	int	Лимит запросов в минуту per-token. Default для `integration` — 60, для `mcp` — 300. Превышение → `429 rate_limited` + `Retry-After`. Подробнее: Лимиты и соглашения.
`expires_at`	timestamp	Срок действия. По истечении токен невалиден (`401`), даже если не revoked. Рекомендуем 30–90 дней для естественной ротации.

Жизненный цикл токена

Выпуск

Только админ BCS через /admin/api-tokens. Полное значение токена показывается единственный раз — в модальном окне сразу после создания. Сохраните в secret-менеджер (vault, 1Password, шифрованный keystore), передайте интегратору через зашифрованный канал. Plaintext в email/мессенджере — не допускается.

Ротация

«Обновить токен в БД» нельзя — полное значение недоступно после выпуска. Ротация = пара действий: выпуск нового + revoke старого. Шаги:

Создать новый токен с теми же company / scopes / ACL.
Передать интегратору; он заменяет в secret-менеджере.
Прогнать smoke с новым (см. Быстрый старт).
Revoke старого через «Отозвать» в admin UI.
Убедиться, что старый возвращает 401 invalid_token.

Revoke

Идемпотентная операция через admin UI или POST /api/v1/admin/api-tokens/{id}/revoke. Эффект мгновенный — следующий же запрос → 401.

Что НЕ делать

Не коммитить токен в git, не вставлять в issue / тикеты / мессенджеры.
Не логировать полное значение токена. В логах — только префикс.
Не передавать токен в query-string. Только в header.
Не использовать один токен для несвязанных интеграций. Изоляция по компаниям и РС — основная гарантия безопасности.

BCS-Коннектор Быстрый старт