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

Все запросы к API требуют аутентификации через Bearer-токен в заголовке Authorization.

## Bearer-токен

Включите ваш API-ключ в заголовок Authorization каждого запроса.

```bash
curl https://api.samreshuuu.ru/api/v1/sessions \
  -H "Authorization: Bearer sk-org-your_api_key"
```

## Примеры на разных языках

**Python**

```python
import requests

API_KEY = "sk-org-your_api_key"
BASE_URL = "https://api.samreshuuu.ru/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(f"{BASE_URL}/sessions", headers=headers)
```

**Node.js**

```typescript
const API_KEY = "sk-org-your_api_key";
const BASE_URL = "https://api.samreshuuu.ru/api/v1";

const response = await fetch(`${BASE_URL}/sessions`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await response.json();
```

**cURL**

```bash
curl https://api.samreshuuu.ru/api/v1/sessions \
  -H "Authorization: Bearer sk-org-your_api_key"
```

## Контекст организации

Если вы являетесь участником нескольких организаций, укажите заголовок X-Org-Id для выбора контекста.

```bash
curl https://api.samreshuuu.ru/api/v1/sessions \
  -H "Authorization: Bearer sk-org-your_api_key" \
  -H "X-Org-Id: org_abc123"
```

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

API-ключи имеют префикс `sk-org-`. Полный секрет показывается только один раз — при создании, сохраните его надёжно. Эндпоинты списка и отзыва возвращают только префикс ключа, никогда не секрет.

## Scopes

Каждый ключ несёт список scope, которые проверяются для каждого эндпоинта. Если у ключа нет нужного scope, запрос завершается ошибкой `403 AUTH_PERMISSION_DENIED`. Ключ со scope `admin` обходит все проверки scope. Новые ключи по умолчанию получают `write:tools`, если scope не указаны явно.

| Scope | Доступ |
| --- | --- |
| `read:tools` | Чтение метаданных инструментов и коннекторов |
| `write:tools` | Выполнение инструментов и коннекторов |
| `read:data` | Чтение данных вашей организации |
| `chat` | Вызов OpenAI-совместимого эндпоинта `/v1/chat/completions` |
| `connector:gateway` | Прямой доступ к шлюзу коннекторов |
| `admin` | Полный доступ — обходит проверки scope |

## Управление ключами

Ключи выпускаются, перечисляются и отзываются в рамках организации. Каждый ключ истекает через `expires_in_days` (по умолчанию 90, диапазон 1–365).

```bash
# Создать ключ — полный секрет возвращается один раз
curl -X POST https://api.samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "production", "scopes": ["chat", "write:tools"], "expires_in_days": 90}'

# Список ключей — только префикс, scopes и last_used_at
curl https://api.samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Отозвать ключ
curl -X DELETE https://api.samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys/$KEY_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

## Ошибки аутентификации

При неверном или истёкшем токене API вернёт ответ с кодом 401.

```json
{
  "detail": {
    "code": "AUTH_TOKEN_EXPIRED",
    "message": "The provided authentication token has expired.",
    "hint": "Generate a new API token in your dashboard."
  }
}
```