<!-- Canonical: https://docs.shopstory.live/docs/guide/authentication -->

# Идентификация приложения

Для выбора клиентского окружения передайте выданный ShopStory идентификатор в query-параметре. Имя параметра зависит от семейства API:

- `/v3/streams` использует `applicationId`;
- `/v2/mini-player/*` использует `application`.

Оба параметра указывают клиентское окружение и направляют запрос к его данным. Они не заменяют пароль, API-ключ или проверку прав. Для каждого запроса используйте имя параметра из OpenAPI-схемы конкретного эндпоинта.

request-streams.sh

```bash
curl --fail-with-body \
  "https://app.shopstory.live/v3/streams?applicationId=<assigned-application-id>&limit=10"
```

Точное значение выдаёт команда ShopStory при подключении. Не подбирайте идентификатор по названию компании и не переносите его между test и production.

## Граница безопасности

`applicationId` виден в браузерных запросах, мобильном трафике, журналах доступа и ссылках. На его секретности нельзя строить контроль доступа.

- Не используйте `applicationId` для защиты персональных данных, административных операций или изменения корзины.
- Не добавляйте в URL токены, cookies и другие секретные данные.
- Для операций в системе ритейлера используйте её штатную сессию, CSRF-защиту и серверную авторизацию.
- CORS ограничивает браузерные origins, но не заменяет аутентификацию.

В публичном контракте нет Bearer-токена. Не отправляйте произвольный `Authorization` и не вводите production credentials в сторонние API-консоли.

## Где выполнять запрос

Выбор зависит от сценария:

| Сценарий | Рекомендуемый путь |
| --- | --- |
| Стандартный web-виджет | Web SDK; ShopStory заранее регистрирует домен клиента |
| Собственный web UI | Backend клиента или согласованный origin браузера |
| Нативное приложение с Mobile SDK | SDK выполняет lookup по контракту поставленного пакета |
| Собственный mobile UI поверх Public API | Backend клиента; приложение получает только нужные поля |
| Серверная синхронизация | Backend-to-backend запрос |

Через backend-прокси клиент может кэшировать и нормализовать ответ, а правила повторов задавать в одном месте. Такой прокси не превращает `applicationId` в учётные данные.

## Обработка ответа

Проверяйте транспортный HTTP-код и поле `status` JSON-конверта. Для части ошибок валидации `/v3/streams` текущий контракт возвращает HTTP `200` и бизнес-код `400` внутри ответа.

Пример ниже выполняется на backend. Пятисекундный deadline — политика этого клиента, а не SLA ShopStory.

request-streams.js

```javascript
export async function getStreams() {
  const applicationId = process.env.SHOPSTORY_APPLICATION_ID;
  if (!applicationId) {
    throw new Error('SHOPSTORY_APPLICATION_ID is not configured');
  }

  const url = new URL('https://app.shopstory.live/v3/streams');
  url.searchParams.set('applicationId', applicationId);
  url.searchParams.set('limit', '10');

  const response = await fetch(url, {
    headers: { Accept: 'application/json' },
    signal: AbortSignal.timeout(5000),
  });

  if (!response.ok) {
    throw new Error(`ShopStory transport error: ${response.status}`);
  }

  const payload = await response.json();
  if (payload.status !== 200) {
    throw new Error(payload.body?.message || 'ShopStory API error');
  }

  return payload.body;
}
```

Пример ошибки идентификации:

```json
{
  "status": 400,
  "body": {
    "error": "invalid",
    "message": "invalid applicationId"
  },
  "serverTime": "2026-09-04T12:00:00Z"
}
```

Не повторяйте такой запрос автоматически: сначала исправьте конфигурацию.

## Эксплуатационный минимум

1. Храните разные значения для test и production в конфигурации приложения.
2. Не записывайте полный query string в аналитику и клиентские crash-отчёты без фильтрации.
3. Проверяйте `status` в конверте и ограничивайте тайм-аут.
4. Обрабатывайте временные ошибки по правилам [Rate limiting](<https://docs.shopstory.live/docs/operations/rate-limits>).
5. Для кэша используйте рекомендации из раздела [Кэширование](<https://docs.shopstory.live/docs/operations/caching>).

Общая модель ответственности описана в разделе [Безопасность](<https://docs.shopstory.live/docs/operations/security>).