JYCODE API GATEWAY — СОЗДАНИЕ И ПОДКЛЮЧЕНИЕ КЛИЕНТСКОГО КЛЮЧА
Версия инструкции: 1.1.0

Для чего нужен ключ
===================
Клиентский ключ защищает ваш JyCode API Gateway. Его передаёт Telegram-бот,
приложение или другой клиент при каждом запросе к https://tulasay.ru.

Ключ выглядит так:
jg_................................................

Не путайте его с ключами DepSearch, NightSearch, Jitler, RaidFind и DeepScan.
Ключ Gateway выдаёте вы сами. Ключи внешних сервисов хранятся только
на сервере в /opt/jycode-gateway/.env.


1. ГДЕ ЛЕЖИТ КЛЮЧ ПОСЛЕ УСТАНОВКИ
=================================
Установщик автоматически создаёт первый ключ и сохраняет его в:

/root/jycode_gateway_client_key.txt

Посмотреть:

sudo cat /root/jycode_gateway_client_key.txt

Проверить, что он прописан в Gateway:

sudo grep '^GATEWAY_API_KEYS=' /opt/jycode-gateway/.env


2. СОЗДАТЬ ЕЩЁ ОДИН КЛЮЧ ОДНОЙ КОМАНДОЙ
========================================
Команда добавит новый ключ в GATEWAY_API_KEYS и перезапустит сервис:

sudo /opt/jycode-gateway/.venv/bin/python \
  /opt/jycode-gateway/scripts/create_gateway_key.py \
  --restart

Новый ключ будет показан в терминале один раз. Скопируйте его в безопасное
место и добавьте в настройки клиента.


3. ПОЛНАЯ ЗАМЕНА ВСЕХ СТАРЫХ КЛЮЧЕЙ
====================================
Команда удалит старые клиентские ключи Gateway, создаст один новый и
перезапустит сервис:

sudo /opt/jycode-gateway/.venv/bin/python \
  /opt/jycode-gateway/scripts/create_gateway_key.py \
  --replace \
  --restart

После этого старые ключи перестанут работать.


4. РУЧНОЕ СОЗДАНИЕ КЛЮЧА
========================
Сгенерировать строку:

sudo -u jycode-api \
  /opt/jycode-gateway/.venv/bin/python \
  /opt/jycode-gateway/scripts/generate_key.py

Открыть конфигурацию:

sudo nano /opt/jycode-gateway/.env

Найти строку:

GATEWAY_API_KEYS=...

Один ключ:

GATEWAY_API_KEYS=jg_ВАШ_КЛЮЧ

Несколько ключей — через запятую, без квадратных скобок:

GATEWAY_API_KEYS=jg_КЛЮЧ_БОТА,jg_КЛЮЧ_ПРИЛОЖЕНИЯ,jg_КЛЮЧ_АДМИНА

Сохранение в nano:
Ctrl+O
Enter
Ctrl+X

Права файла:

sudo chown jycode-api:jycode-api /opt/jycode-gateway/.env
sudo chmod 600 /opt/jycode-gateway/.env

Применить:

sudo systemctl restart jycode-gateway
sudo systemctl status jycode-gateway --no-pager -l


5. ПРОВЕРИТЬ КЛЮЧ
=================
Подставьте свой ключ вместо jg_ВАШ_КЛЮЧ:

curl -sS https://tulasay.ru/v1/types \
  -H "X-API-Key: jg_ВАШ_КЛЮЧ"

Или через Bearer:

curl -sS https://tulasay.ru/v1/types \
  -H "Authorization: Bearer jg_ВАШ_КЛЮЧ"

При правильном ключе сервер вернёт JSON со списком типов поиска.
При неправильном ключе:

HTTP 401
{"detail":"Неверный ключ доступа"}


6. ПРИМЕР ПОИСКА
================
curl -sS -X POST "https://tulasay.ru/v1/search" \
  -H "X-API-Key: jg_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "8382799213",
    "search_type": "telegram",
    "include_raw": false
  }'


7. ЧТО ПИСАТЬ В TELEGRAM-БОТЕ
=============================
В .env Telegram-бота:

GATEWAY_BASE_URL=https://tulasay.ru
GATEWAY_API_KEY=jg_ВАШ_КЛЮЧ

В Python-запросе:

headers = {
    "X-API-Key": os.environ["GATEWAY_API_KEY"],
    "Content-Type": "application/json",
}

response = await client.post(
    f"{os.environ['GATEWAY_BASE_URL']}/v1/search",
    headers=headers,
    json={
        "query": "8382799213",
        "search_type": "telegram",
        "include_raw": False,
    },
)


8. КАК ОТОЗВАТЬ КЛЮЧ
====================
Откройте:

sudo nano /opt/jycode-gateway/.env

Удалите ненужный ключ из строки GATEWAY_API_KEYS, затем:

sudo systemctl restart jycode-gateway

Проверьте:

curl http://127.0.0.1:8080/healthz


9. БЕЗОПАСНОСТЬ
===============
— Не отправляйте ключи в публичные чаты, GitHub и скриншоты.
— Не помещайте рабочий .env в архив проекта.
— Для бота и приложения используйте разные ключи.
— При утечке сразу создайте новый ключ с --replace.
— К серверу обращайтесь через HTTPS: https://tulasay.ru.
— ALLOW_UNAUTHENTICATED должен оставаться false.
— Файл .env должен иметь права 600.
— Ключи внешних пяти сервисов клиентам не передаются.


10. ПОЛЕЗНЫЕ АДРЕСА
===================
Красивая документация:
https://tulasay.ru/docs

Интерактивный Swagger:
https://tulasay.ru/swagger

OpenAPI JSON:
https://tulasay.ru/openapi.json

Проверка здоровья:
https://tulasay.ru/healthz

Логи Gateway:
sudo journalctl -u jycode-gateway -f