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

Каждый запрос к Lumo B2B API подписывается API-ключом. Ключ выдаётся не компании целиком, а каждому участнику команды: у владельца, у бухгалтера и у вашего сервера могут быть разные ключи с разными правами.

Компанию подключает менеджер — напишите в Telegram. В зависимости от способа подключения вы получите:

• вход владельца в личный кабинет (email и пароль) и API-ключ владельца;
• или общий API-ключ компании без входа в кабинет — см. Общий ключ компании.

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

Ключ имеет вид lb2b_ + 32 шестнадцатеричных символа. Рекомендуемый способ передачи — заголовок X-API-Key:

curl -X GET 'https://b2b.lumowallet.io/wallets/balance' \
  -H 'X-API-Key: lb2b_5f7f1f7b7f034dbf81b0b8b8d7c0b9f1'

Также поддерживаются:

• Authorization: Bearer <api-key>;
• query-параметр ?api_key=<api-key> — не рекомендуется: ключ попадает в логи прокси, историю браузера и в поле path ответов с ошибкой.

Если передано несколько вариантов, используется первый по порядку: Authorization, затем X-API-Key, затем api_key.

Ключ действует с правами своего участника. Ключ владельца даёт полный доступ, ключ участника — только то, что ему выдали. Если права не хватает, API отвечает 403 PERMISSION_DENIED и называет недостающее право в поле required:

{
  "statusCode": 403,
  "error": "PERMISSION_DENIED",
  "errorCode": "PERMISSION_DENIED",
  "message": "Missing required permission: cards.recharge",
  "required": "cards.recharge",
  "details": { "required": "cards.recharge" },
  "path": "/cards/recharge",
  "timestamp": "2026-10-03T10:00:00.000Z",
  "requestId": "439436bd-201c-4084-9063-58cfa2cd40ad"
}

Каталог прав и то, какое право нужно каждому эндпоинту, — в разделе Команда и права.

:::tip Отдельный ключ для сервера

Заведите для интеграции отдельного участника только с нужными правами. Тогда ротация ключа сервера не затронет людей, а утечка ключа не даст доступа к управлению командой.

:::

Вход по email и паролю возвращает не API-ключ, а сессионный токен:

curl -X POST 'https://b2b.lumowallet.io/auth/company/login' \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "password": "********"}'

{
  "company": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Acme LLC",
    "email": "[email protected]"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Токен действует 7 дней и принимается всеми эндпоинтами вместо ключа — в заголовке Authorization: Bearer <token>. Права записываются в токен в момент входа: если владелец поменял участнику права, они применятся к сессии после повторного входа. К API-ключу изменения прав применяются сразу.

Для серверной интеграции используйте API-ключ, а не сессию.

curl -X POST 'https://b2b.lumowallet.io/auth/company/api-key/reveal' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "apiKey": "lb2b_5f7f1f7b7f034dbf81b0b8b8d7c0b9f1",
  "source": "encrypted"
}

Возвращает ключ того участника, от чьего имени сделан запрос. Нужно право apikey.regenerate. Для старых ключей, выпущенных до появления этой функции, восстановить значение нельзя — придёт 404, и ключ нужно перевыпустить.

curl -X POST 'https://b2b.lumowallet.io/auth/company/regenerate-key' \
  -H 'X-API-Key: YOUR_CURRENT_API_KEY'

{
  "company": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Acme LLC",
    "email": "[email protected]"
  },
  "apiKey": "lb2b_0c1d2e3f405162738495a6b7c8d9e0f1"
}

Перевыпускается ключ того участника, от чьего имени сделан запрос. Его прежний ключ сразу перестаёт работать, ключи остальных участников не меняются. Нужно право apikey.regenerate.

Компания может работать и с общим ключом, не привязанным к участнику: такой ключ выдаётся при подключении без входа владельца, и он же остался у компаний, подключённых до появления команд. Общий ключ даёт полный доступ, но действия, которым нужен конкретный участник, с ним недоступны:

• regenerate-key и api-key/reveal отвечают 400 BAD_REQUEST — перевыпустить общий ключ можно через менеджера;
• приглашать, менять и удалять участников нельзя — просматривать список участников и приглашений можно.

Ограничений по IP-адресам нет: регистрировать адреса своих серверов нигде не нужно.

GET /auth/company/profile

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Acme LLC",
  "email": null,
  "loginEmail": null,
  "contactEmail": "[email protected]",
  "contactTelegram": "@acme_support",
  "isActive": true,
  "webhookUrl": "https://your-server.com/webhooks/lumo",
  "hasWebhookSecret": true,
  "depositForwardAddress": "TQ2x4bW8ZGq3NkL2bUQvX8sJ7d1cQh1xYz",
  "balance": 1000.5,
  "frozenBalance": 52.63,
  "userId": "3c9e2f6a-1b7d-4c55-9a0e-7d2f4b8c1e90",
  "role": "owner",
  "permissions": ["*"],
  "isOwner": true,
  "cards": {
    "enabled": true,
    "openingFeeUsdt": 5,
    "commissionBps": 80,
    "minInitialDepositUsdt": 10,
    "minRechargeUsdt": null,
    "testMode": false
  },
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-10-01T12:00:00.000Z"
}

• userId, role, permissions, isOwner относятся к участнику, от чьего имени сделан запрос. Для ключа компании старого образца userId и role равны null, permissions — ["*"].
• email и loginEmail заполнены только у компаний старого образца; email участника приходит в ответе login.
• hasWebhookSecret показывает, задан ли секрет подписи вебхуков, — сам секрет здесь не отдаётся.
• cards — условия программы карт, см. Карты.

Изменить профиль — PATCH /auth/company/profile (право settings.write). Все поля необязательные, меняются только переданные:

Ответ — обновлённый профиль.

• Храните API-ключ в безопасном месте (env-переменные, secrets manager).
• Не передавайте ключ в URL и не пишите его в логи.
• Выдавайте ключам только нужные права и периодически ротируйте их.
• Используйте HTTPS для всех запросов.

Формат ошибок — в разделе Обработка ошибок.