Ключи API — tnea_ и tnsr_¶

NumerologyAPI использует два семейства ключей API. Оба типа выглядят одинаково, генерируются в том же защищённом 80-символьном формате и аутентифицируются с помощью того же заголовка X-API-Key — но они учитываются по-разному и предназначены для разных продуктов.

1. Формат ключа и безопасность¶

Каждый ключ имеет длину ровно 80 символов:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Префикс из 4 символов определяет тип ключа; остальные 75 символов генерируются с помощью криптографически защищённого источника случайных чисел.
• Ключи хранятся на сервере в виде SHA-256 хеша. Ключ в открытом виде показывается только один раз — при создании.
• Если ключ когда-либо был скомпрометирован, немедленно ротируйте его в панели управления.

2. Платформенные ключи (tnea_)¶

Платформенные ключи — это стандартные ключи для интеграции NumerologyAPI в ваш собственный продукт: веб-сайты, мобильные приложения и серверные сервисы.

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

Отправляйте ключ в каждом запросе с заголовком X-API-Key:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

Учёт¶

Тарифицируемые вызовы /api/v1 списываются из кошелька кредитов вашей организации (оплата по мере использования). Вы можете пополнить кошелёк в любой момент из панели управления.

Правило канала: платформенные ключи не должны отправлять заголовок X-Numora-Client. Его отправка возвращает 403 — этот заголовок зарезервирован для десктопного канала.

3. Ключи Numora Studio (tnsr_)¶

Ключи Numora Studio аутентифицируют десктопное приложение Numora Studio (macOS/Windows), которое практикующие специалисты используют для генерации отчётов для клиентов. Это родственный платформенным ключам тип с идентичным форматом, но они тарифицируются против лимита тарифа Numora Studio plan организации, а не против платформенных кредитов.

Выпуск ключа¶

Ключ tnsr_ создаётся одним из двух способов:

• через процесс входа в десктопном приложении (страница согласия в браузере выпускает ключ автоматически), или
• вручную на странице API Keys в панели управления (/api-keys).

Сигнатура канала (обязательна)¶

Каждый вызов, совершённый с ключом tnsr_, должен включать заголовок десктопного канала:

Принудительное соблюдение на сервере:

• ключ tnsr_ без заголовка X-Numora-Client → 403.
• ключ tnea_ с заголовком X-Numora-Client → 403.

Учёт¶

• Тарифицируемые вызовы /api/v1 списываются из лимита тарифа Numora Studio plan организации (один общий пул для всех ключей tnsr_ организации).
• Для каждого ключа tnsr_ существует переключатель резервных кредитов: когда лимит тарифа исчерпан, ключ может перейти на платформенные кредиты организации (по умолчанию выключено).
• Если лимит исчерпан и резерв не включён, вызовы возвращают 429.

Привязка к устройствам (необязательно)¶

Ключ tnsr_ может быть привязан к зарегистрированным устройствам. Если привязка включена, каждый запрос должен содержать X-Numora-Device-Id, зарегистрированный за организацией; незарегистрированные устройства отклоняются с кодом 403.

Эндпоинты, доступные только для десктопа¶

Некоторые эндпоинты зарезервированы для десктопного канала и возвращают 403 для ключей tnea_:

• POST /api/v1/numora/report-bundle — полный отчёт для клиента одним вызовом
• POST /api/v1/numora/order — покупка плана/лимита внутри приложения
• POST /api/v1/numora/devices/register — регистрация десктопной установки
• GET /api/v1/numora/studio-status — балансы и счётчики лимитов десктопа

Совет: в тарифицируемых ответах также передаются заголовки X-Remaining-Credits и X-Remaining-Tokens, чтобы вы могли отслеживать текущие остатки без дополнительных вызовов.

4. Управление ключами (Панель управления)¶

Страница API Keys (/api-keys) в панели управления — центр управления обоими типами ключей.

Роли: роли admin и developer могут создавать и управлять ключами. Роль finance не может создавать продакшн-ключи API. Финансовые операции (покупка планов, пополнения) доступны только ролям admin и finance.

Несколько ключей: организации могут иметь много ключей обоих типов — например, по одному ключу tnsr_ на каждого практикующего специалиста или на каждую десктопную установку. Лимиты являются общими для организации, поэтому ключи никогда не «конкурируют» за собственный баланс.

5. Рекомендации¶

• Относитесь к ключам как к паролям. Никогда не встраивайте их в клиентский код, публичные репозитории или журналы.
• Используйте переменные окружения или менеджер секретов в вашем бэкенде.
• Немедленно ротируйте ключ, если он скомпрометирован или если команду покинул сотрудник.
• Используйте один ключ tnsr_ на десктопную установку, чтобы упростить управление устройствами и отзыв ключей.
• Включайте привязку к устройствам для организаций с высокими требованиями к безопасности.
• Следите за использованием в панели управления, чтобы вовремя заметить неожиданные всплески.

6. Частые вопросы¶

Может ли ключ tnsr_ вызывать обычные платформенные эндпоинты? Да. Ключи Numora Studio аутентифицируют всю поверхность /api/v1; такие вызовы тарифицируются против лимита тарифа Numora Studio plan.

Может ли ключ tnea_ вызывать эндпоинты /numora/*, доступные только для десктопа? Нет. Эндпоинты, доступные только для десктопа, возвращают 403 для платформенных ключей.

Почему при вызове с моим ключом tnsr_ я получаю 403? Скорее всего, отсутствует заголовок X-Numora-Client или идентификатор приложения не совпадает. Убедитесь, что каждый запрос включает X-Numora-Client: numora-studio/<version>.

Почему с моим ключом tnea_ я получаю 403? Платформенные ключи не должны содержать заголовок X-Numora-Client — удалите его.

Что произойдёт, когда мой лимит закончится? Тарифицируемые вызовы возвращают 429, если на вашем ключе tnsr_ не включены резервные кредиты (или если вы не пополнили платформенный кошелёк для ключей tnea_).

Связанные материалы¶

• Начало работы
• Цены
• Корпоративные решения