# API Токены

API токены — рекомендуемый способ аутентификации для ботов, скриптов и интеграций.

## Преимущества

✅ **Безопаснее**: токены можно отзывать отдельно, не меняя пароль админа  
✅ **Гранулярные права**: можно ограничить доступ (в будущем)  
✅ **Срок действия**: токены могут автоматически истекать  
✅ **Аудит**: видно какой токен и когда использовался  
✅ **Изоляция**: разные токены для разных ботов/сервисов  

## Создание токена

### Через веб-панель (UI)

1. Войдите в панель: `https://your-panel.com`
2. Перейдите в раздел **API Токены** 🔑
3. Нажмите **Создать токен**
4. Заполните форму:
   - **Название**: например "Telegram бот"
   - **Срок действия**: опционально, оставьте пустым для бессрочного
5. Нажмите **Создать**
6. **Важно!** Скопируйте токен сразу — он больше не будет показан

### Через API (программно)

```python
import httpx

# Логинимся как админ
response = httpx.post(
    "https://your-panel.com/api/auth/login",
    json={"login": "admin", "password": "secret"}
)
jwt_token = response.json()["access_token"]

# Создаём API токен
response = httpx.post(
    "https://your-panel.com/api/tokens",
    headers={"Authorization": f"Bearer {jwt_token}"},
    json={
        "name": "My Bot",
        "expires_at": "2027-12-31T23:59:59Z"  # опционально
    }
)
api_token = response.json()["token"]
print(f"Токен: {api_token}")
```

## Использование токена

### Python SDK

```python
from amnezio import AmnezioClient

async with AmnezioClient(
    base_url="https://your-panel.com",
    api_token="amz_xxxxxxxxxxxxxxxxxx"
) as client:
    users = await client.users.list()
```

### Прямые HTTP запросы

```python
import httpx

response = httpx.get(
    "https://your-panel.com/api/users",
    headers={"Authorization": "Bearer amz_xxxxxxxxxxxxxxxxxx"}
)
```

```bash
# curl
curl -H "Authorization: Bearer amz_xxxxxxxxxxxxxxxxxx" \
     https://your-panel.com/api/users
```

## Управление токенами

### Просмотр токенов

```python
# Получить список всех токенов
response = httpx.get(
    "https://your-panel.com/api/tokens",
    headers={"Authorization": f"Bearer {jwt_token}"}
)
tokens = response.json()
```

### Удаление токена

```python
# Удалить токен по ID
httpx.delete(
    f"https://your-panel.com/api/tokens/{token_id}",
    headers={"Authorization": f"Bearer {jwt_token}"}
)
```

Или через веб-панель: нажмите 🗑️ рядом с токеном.

## Безопасность

### Хранение токенов

❌ **НЕ ДЕЛАЙТЕ ТАК:**
```python
# Не хардкодьте токен в коде
client = AmnezioClient(api_token="amz_secret123")
```

✅ **ПРАВИЛЬНО:**
```python
import os

# Храните в переменных окружения
api_token = os.getenv("AMNEZIO_API_TOKEN")
client = AmnezioClient(api_token=api_token)
```

```bash
# .env файл (не коммитьте в git!)
AMNEZIO_API_TOKEN=amz_xxxxxxxxxxxxxxxxxx
```

### Ротация токенов

Рекомендуется периодически обновлять токены:

1. Создайте новый токен
2. Обновите конфигурацию бота
3. Удалите старый токен

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

```
amz_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

- Префикс: `amz_`
- Длина: 47 символов
- Генерация: `secrets.token_urlsafe(32)`
- Хранение: SHA256 хеш в БД

## Troubleshooting

### "Invalid credentials"

- Проверьте, что токен начинается с `amz_`
- Убедитесь, что токен не истёк (проверьте `expires_at`)
- Токен мог быть удалён — создайте новый

### "Token expired"

Токен истёк. Создайте новый или используйте без срока действия.

### Токен не работает

```python
# Проверка токена
response = httpx.get(
    "https://your-panel.com/api/users",
    headers={"Authorization": f"Bearer amz_xxx"}
)
print(response.status_code, response.text)
```

Если 401 — токен недействителен, создайте новый.
