Аутентификация: лицензионный ключ, seats и токены платформ
Socialift SDK работает по лицензионному ключу slk_.... Ключ подписан Ed25519 и сначала проверяется офлайн, затем перед первым запросом SDK получает у сервера лицензий lease на 12 часов. Если сервер недоступен, работа продолжается 7 дней с момента последнего успешного подтверждения. Каждое окружение занимает один seat — в контейнерах задавайте SOCIALIFT_INSTANCE_ID.
Обновлено:
Какие ключи используются при работе с Socialift?
Есть три вида ключей, и их важно не путать. Лицензионный ключ (slk_...) — право использовать Socialift SDK; платформам он не отправляется. Ключи developer app (Meta App ID и secret, client-данные LinkedIn и TikTok, api_id/api_hash Telegram) представляют ваше приложение платформе. Токены платформ (OAuth access token, токен страницы, токен бота, сессия Telegram) дают право действовать от имени конкретного пользователя или аккаунта.
Лицензионный ключ, ключ приложения и токен платформы: в чём разница?
| Лицензионный ключ | Ключ developer app | Токен платформы | |
|---|---|---|---|
| Пример | slk_... | Meta App ID + App Secret; LinkedIn Client ID/Secret; TikTok Client Key/Secret; Telegram api_id/api_hash | Access token пользователя или страницы, refresh token TikTok, токен бота, сессия Telegram |
| Кто выдаёт | Кабинет Socialift → «Tokenlar» (токены) | Developer-консоль платформы | OAuth, @BotFather или вход по телефону |
| Зачем | Разрешение на работу SDK | Представить приложение платформе: OAuth, подписи | Запросы от имени конкретного аккаунта |
| Как передаётся в SDK | SOCIALIFT_LICENSE_KEY или license_key= | Конструктор: Facebook(app_id=..., app_secret=...) или from_env() | Аргумент каждого метода: fb.pages(token) |
| Где хранить | Переменная окружения сервера или secret manager | Переменная окружения сервера или secret manager | Ваша база, в зашифрованном виде |
Примечания и ограничения
Разделы кабинета «Kalitlar» (ключи) и «Ulanishlar» (подключения) нужны для Playground и сервера Socialift. SDK в вашем приложении с ними не связан — ключи и токены вы передаёте сами.
Как передать лицензионный ключ в SDK?
Есть три способа. Приоритет: аргумент license_key= → SOCIALIFT_LICENSE_KEY → set_license_key().
import os
import socialift
from socialift import Facebook
# 1) Переменная окружения (рекомендуется): SOCIALIFT_LICENSE_KEY=slk_...
fb = Facebook.from_env()
# 2) Явный аргумент — важнее переменной окружения
fb = Facebook.from_env(license_key=os.environ["BILLING_SLK"])
# 3) На весь процесс (notebook, тесты)
socialift.set_license_key("slk_...")Внимание: если задана SOCIALIFT_LICENSE_KEY, она важнее set_license_key(). Если в notebook кажется, что ключ «не меняется», сначала проверьте переменную окружения.
Ключ проверяется не при создании клиента, а перед первым запросом. Все клиенты с одним ключом в одном процессе используют одну активацию. TelegramAccount тоже принимает license_key=.
Хелперы вебхуков (socialift.webhooks) и функции socialift.crypto не ходят в сеть и лицензию не проверяют.
Как проверяется лицензия?
Офлайн: формат и подпись
Ключ имеет вид
slk_<payload>.<подпись>. SDK проверяет префикс, формат и подпись Ed25519 встроенным публичным ключом, а также срок действия внутри ключа. Если формат или подпись неверны, сразу, без сети, возникаетLicenseInvalid. Если срок в ключе истёк, SDK 1.3+ сначала запрашивает текущий срок у сервера (токен мог быть продлён), а офлайн-режим и SDK 1.2.x сразу выдаютLicenseExpired.Онлайн: получение lease
Перед первым запросом SDK отправляет серверу лицензий ключ, отпечаток окружения (хеш), версии SDK и Python и получает lease. Срок по умолчанию — 12 часов, его задаёт сервер. Пока lease действует, повторных обращений к серверу нет.
Автоматическое продление
Когда lease истекает, он продлевается перед следующим запросом. Если сервер изменил тариф или возможности, новое состояние применяется без замены ключа. При продлении токена кабинет показывает переподписанный ключ с тем же
key_id: SDK 1.3+ сам получает новый срок с сервера, а с версией 1.2.x из PyPI или приSOCIALIFT_LICENSE_OFFLINE=1заменитеSOCIALIFT_LICENSE_KEYна этот ключ.Офлайн grace-период
Если сервер недоступен или вернул ошибку, кроме 403, и с последнего успешного подтверждения прошло меньше 7 дней, SDK продолжает работать и перепроверяет сервер каждый час. Если прошло больше 7 дней или записи о подтверждении нет —
LicenseError.Отзыв — сразу
Если сервер вернул 403 (ключ отозван, лимит seats исчерпан или окружение заблокировано), grace не действует: сразу возникает
LicenseRevoked, а кешированное подтверждение удаляется.
Переменные окружения для лицензии
| Переменная | По умолчанию | Назначение |
|---|---|---|
SOCIALIFT_LICENSE_KEY | нет | Лицензионный ключ slk_... |
SOCIALIFT_INSTANCE_ID | хеш hostname, архитектуры и MAC-адреса | Стабильное имя окружения — по нему считается seat |
SOCIALIFT_LICENSE_OFFLINE | выключено | 1, true или yes — только офлайн-проверка подписи, без обращения к серверу |
SOCIALIFT_LICENSE_ENDPOINT | https://api.socialift.uz/api/v1/license | Адрес сервера лицензий; не меняйте без указания Socialift |
XDG_CACHE_HOME | ~/.cache | Сюда пишется socialift/license.json (время последнего подтверждения) — на нём держится grace-период |
естьнет
Если исходящий трафик ограничен (firewall, egress-правила), разрешите HTTPS к api.socialift.uz.
Как работает офлайн grace-период?
Grace-период отсчитывается не от момента, когда сервер перестал отвечать, а от последней успешной активации. SDK записывает это время в ~/.cache/socialift/license.json (или $XDG_CACHE_HOME/socialift/license.json). Если сервер недоступен и с того момента не прошло 7 дней, SDK пишет предупреждение в лог и продолжает работу.
При пересоздании контейнера файл пропадает. Если новый контейнер стартует, когда сервер недоступен, записи для grace нет, и первый запрос завершится LicenseError. Чтобы grace переживал деплои, подключите каталог кеша к постоянному volume или направьте туда XDG_CACHE_HOME.
Ответы сервера с кодом 403 — отозванный ключ, лимит seats, заблокированное окружение — в grace не попадают.
Когда нужен SOCIALIFT_LICENSE_OFFLINE?
Для окружений без выхода во внешнюю сеть: изолированный CI или закрытый контур. В этом режиме проверяются только подпись ключа и срок внутри него, к серверу лицензий SDK не обращается.
Последствия: отзыв ключа на сервере не действует, изменения тарифа не доходят, подписанный пакет правил, который приходит вместе с lease (наборы полей Graph, таблица сопоставления полей лидов), не обновляется — SDK работает с кешированным или минимальным базовым набором. Для обычного продакшена режим не рекомендуется.
Что такое seat и зачем SOCIALIFT_INSTANCE_ID в Docker и Kubernetes?
Seat — число окружений, в которых ключ может работать одновременно. Окружение определяется отпечатком: SHA-256 от SOCIALIFT_INSTANCE_ID, если он задан, иначе хеш hostname, архитектуры и MAC-адреса. Docker выдаёт каждому новому контейнеру новые hostname и MAC, поэтому каждый деплой занимает новый seat, а после исчерпания лимита SDK останавливается с LicenseRevoked (сообщение «Seat chegarasi» — лимит seats).
Уже зарегистрированный отпечаток при повторной активации новый seat не занимает. Занятые seats сами не освобождаются: их видно в «Tokenlar» (токены) → «Tekshirish va muhitlar» (проверка и окружения), для освобождения напишите в поддержку.
Давайте каждому окружению одно стабильное имя, например my-app-prod и my-app-staging.
Имя окружения в Kubernetes и Docker
# Kubernetes Deployment (фрагмент)
env:
- name: SOCIALIFT_INSTANCE_ID
value: my-app-prod
- name: SOCIALIFT_LICENSE_KEY
valueFrom:
secretKeyRef:
name: socialift
key: license-key
# Docker:
# docker run -e SOCIALIFT_INSTANCE_ID=my-app-prod -e SOCIALIFT_LICENSE_KEY my-app:latestПроверка лицензии при старте приложения
Чтобы узнать о проблеме при деплое, а не на первом запросе пользователя.
import asyncio
from socialift import LicenseError, LicenseManager
async def check_license():
try:
lic = await LicenseManager.get().ensure()
except LicenseError as exc:
raise SystemExit(f"Лицензия Socialift не работает: {exc}")
print(lic.key_id, lic.plan.value, lic.expires_at, lic.seats)
asyncio.run(check_license())LicenseManager.get() находит ключ так же, как клиенты, и возвращает общий с ними менеджер: внутри приложения последующие запросы не активируют лицензию повторно. Отдельный процесс на той же машине приходит с тем же отпечатком и новый seat не занимает.
lic.features — набор возможностей, открытых в вашем тарифе.
Ошибки лицензии и как их исправить
| Ошибка | Когда возникает | Что делать |
|---|---|---|
LicenseError | Базовый класс. Сервер не подтвердил лицензию, а grace нет: сетевая ошибка, сбой сервера или отклонённый ключ вне grace-периода | Проверьте сеть и ключ — причина в тексте сообщения |
LicenseRequired | Ключ не найден: license_key=, SOCIALIFT_LICENSE_KEY и set_license_key() пусты | Задайте переменную окружения |
LicenseInvalid | Префикс не slk_, формат повреждён, подпись не сходится или не установлен cryptography | Скопируйте ключ заново целиком, без пробелов |
LicenseExpired | Срок токена истёк (в SDK 1.2.x и офлайн-режиме — дата внутри ключа) | Продлите токен в «Tokenlar» (токены); в SDK 1.2.x или офлайн-режиме замените и ключ на переподписанный |
LicenseRevoked | Сервер вернул 403: ключ отозван, лимит seats исчерпан или окружение заблокировано | Прочитайте сообщение; при лимите seats задайте стабильный SOCIALIFT_INSTANCE_ID |
FeatureNotInPlan | Метод требует возможность вне вашего тарифа; есть атрибуты feature и plan | Смените тариф |
Все они наследуют LicenseError → SocialiftError, но не ApiError — с ошибками платформ не смешиваются.
Занимает ли проверка ключа в кабинете seat?
Нет. Кнопка «Tekshirish va muhitlar» (проверка и окружения) на странице «Tokenlar» (токены), как и «Tekshirish» (проверить) в «Qo'llanma» (руководство), не вызывает активацию SDK, а только читает состояние из базы. Нажимать можно сколько угодно.
В результате видно: работает ли ключ с SDK (если нет — причина), тариф, занятые seats (например, 1 / 1), срок lease в часах, время последней активации, открытые возможности и таблицу «Muhitlar» (окружения): начало отпечатка, версии SDK и Python, первое и последнее появление, число активаций. Если все seats заняты, страница отдельно предупреждает об этом.
Замена или отзыв ключа
Получите новый ключ
«Tokenlar» (токены) → «Yangi token» (новый токен). Это отдельный токен со своим сроком и seat. Одновременно в аккаунте может быть до 5 активных токенов.
Замените ключ во всех окружениях
Обновите
SOCIALIFT_LICENSE_KEYв secret manager или переменных окружения;SOCIALIFT_INSTANCE_IDне меняйте.Перезапустите процессы
SDK кеширует ключ внутри процесса, поэтому новый ключ начнёт использоваться после рестарта.
Отзовите старый или утёкший ключ
Кнопки отзыва для пользователя в кабинете нет — напишите
key_idключа на hello@socialift.uz. Отзыв вступает в силу при следующем продлении lease (до 12 часов), и SDK остановится сLicenseRevoked.
Частые вопросы
Проверяется ли лицензионный ключ при каждом запросе к API?
Нет. К серверу лицензий SDK обращается при старте и каждый раз, когда истекает lease (по умолчанию 12 часов). Запросы SDK к Instagram, TikTok и другим платформам через сервер Socialift не проходят.
Остановится ли продакшен, если сервер лицензий недоступен?
В течение 7 дней с последнего успешного подтверждения — нет: SDK работает в офлайн grace-режиме и проверяет сервер каждый час. Для этого должен сохраниться файл кеша с подтверждением (~/.cache/socialift/license.json) — в контейнерах подключите его к постоянному volume.
На скольких серверах можно использовать один ключ?
В стольких окружениях, сколько seats в ключе. Новый токен из кабинета выдаётся с 1 seat; сколько занято, показывает «Tekshirish va muhitlar» (проверка и окружения). Если нужны дополнительные seats, свяжитесь с Socialift.
Чем лицензионный ключ отличается от Meta App Secret?
Лицензионный ключ — право использовать SDK, он отправляется только на сервер лицензий Socialift. App Secret — секрет вашего приложения в Meta: для обмена кода OAuth, appsecret_proof и подписи вебхуков. Они не заменяют друг друга, и оба хранятся только на сервере.
Вызвал set_license_key(), но используется другой ключ. Почему?
Порядок приоритета: сначала аргумент license_key=, затем SOCIALIFT_LICENSE_KEY, и только потом set_license_key(). Если переменная окружения задана, она важнее set_license_key() — уберите её или передайте ключ аргументом.
В Docker после каждого деплоя ошибка «Seat chegarasi» (лимит seats). Что делать?
Задайте стабильный SOCIALIFT_INSTANCE_ID (например, my-app-prod) — тогда следующие деплои останутся в одном seat. Seats, занятые прошлыми деплоями, сами не освобождаются: посмотрите их в «Tekshirish va muhitlar» и напишите в поддержку, чтобы их освободить.