> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Публичный API, ключи и вебхуки

Версионируемая REST-поверхность, на которой строят ваши клиенты.

## Прежде чем начать

Откройте загруженный проект supastack в Visual Studio Code, используя «Файл» → «Открыть папку», затем выберите «Терминал» → «Новый терминал». Корень репозитория — это папка, содержащая package.json, приложения и пакеты. Запустите команду ниже и оставьте терминал открытым. Если команда не распознается, завершите руководство по установке инструмента, прежде чем продолжить.

Сначала прочтите руководство по платформе. Сервер — это процесс приложения, который отвечает на запросы браузера или телефона. Веб читает apps/web/.env.local, Expo читает apps/mobile/.env.local, а команды миграции базы данных читают корневой .env. Демонстрация без базы данных / панели мониторинга отделена от реальных учетных записей / аутентификации, для которых необходимо перенести Postgres. Для оформления заказа только на телефоне или компьютере требуется отдельно работающий веб-сервер.

[Установите инструменты и получите код](https://supastack.dev/ru/docs/web/before-you-start.md)

[Изучение команд, файлов и конфигурации](https://supastack.dev/ru/docs/web/terminal-basics.md)

[Пройдите руководство по первому запуску в Интернете](https://supastack.dev/ru/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## Настройка и конфигурация

packages/api определяет версионируемый контракт: zod-схемы для каждого запроса и ответа, обёртку ошибок и документ OpenAPI, отдаваемый на /api/v1/openapi и отрисованный на /api/docs. API-ключи пространства создаются в Настройки → Разработчики; открытый текст показывается один раз, далее сохраняется только хэш ключа.

Ключи имеют префикс (sk_<env>_…), scope (по умолчанию read) и разрешаются в рабочее пространство при каждом запросе. Подписки исходящих вебхуков управляются на той же поверхности «Разработчики».

```
GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…
```


## Рабочий процесс внедрения

Аутентифицируйтесь Bearer-ключом; сервер разрешает пространство из ключа, а не из переданного клиентом id. Держите формы ответов версионируемыми — аддитивные изменения внутри v1, ломающие — за новой версией.

Для исходящих вебхуков подпишите URL конечной точки на каталог событий; доставки подписываются и логируются, чтобы потребители могли проверять и воспроизводить. Используйте webhook-events.ts для каталога и webhook-delivery.ts для попыток.


## Проверка и устранение неполадок

Проверьте, что отозванный ключ возвращает 401, что ключ с недостаточным scope отклоняется и что документ OpenAPI парсится. Для вебхуков протестируйте проверку подписи, повторную доставку после сбоя и то, что полезные нагрузки событий никогда не несут секреты провайдера.


## Вперёд

[Файловое хранилище](https://supastack.dev/ru/docs/web/storage.md)