Authentication

NurCore API требует авторизации на всех endpoints без исключений — даже на read-only каталоге аэропортов и тарифов. Это позволяет правильно ограничивать запросы, отслеживать использование и блокировать злоупотребления.

Два типа API Keys

NurCore выдаёт два разных типа ключей:

Тип	Префикс	Где хранить	Что доступно
Publishable	`pk_live_...`	Mobile bundle, frontend JS, React app	Read-only catalog + создание брони от лица пассажира + magic-link issuance
Secret	`sk_live_...`	Только server-side (env vars, secret manager)	Все endpoints — включая partner wallet, refunds, exchange

Когда использовать какой ключ

Сценарий	Ключ
Backend B2B-агентства	`sk_live_*` (agency)
Backend mobile-приложения (BFF)	`sk_live_*` (consumer_app)
Mobile app встраивает в bundle	`pk_live_*` (consumer_app)
Frontend сайта-агрегатора	`pk_live_*` (consumer_app)
Webhook handler авиакомпании	`sk_live_*` (partner)

Sandbox vs Production

Окружение	Префикс
Sandbox	`pk_test_` / `sk_test_`
Production	`pk_live_` / `sk_live_`

Headers

Все запросы (кроме magic-link) требуют 3 заголовка:

X-API-Key: pk_live_abc123...
X-Client-Id: <your_client_id>
X-Client-Type: agency | consumer_app | kiosk

Типы клиента

client_type	Назначение
`agency`	B2B-турагентства, OTA, консолидаторы
`consumer_app`	Mobile-приложения и публичные сайты
`kiosk`	Терминалы саморегистрации в аэропорту

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

Secret keys — server-side only

Никогда не размещайте sk_live_* в:
- Frontend bundle (mobile / SPA)
- Public git-репозиториях
- Логах / stack traces
- Frontend cookies / localStorage
Используйте .env файлы или secret-manager (AWS Secrets Manager, HashiCorp Vault, Doppler)
При компрометации — немедленно ротация через partners@nurcore.kg

Publishable keys — restricted by design

Publishable key создан для embedding в bundle / frontend JS — он публичен, и это нормально. Защита от abuse работает через:

Origin allowlist — ключ работает только с зарегистрированных доменов (*.your-airline.com) или mobile bundle IDs (com.yourairline.app)
Read-only scope — нельзя получить чужие брони, инициировать refunds, делать pay-with-balance
Жёсткий rate limit — 120 req/min per key vs 600 для secret
No PII access — нельзя получить данные пассажиров других броней

BFF-паттерн (рекомендуется)

Best practice для mobile / website — Backend for Frontend:

[Mobile / Browser] → [Your BFF] → [NurCore API]
                       ^
                       | sk_live_* в env
                       | + бизнес-логика
                       | + дополнительный rate limit

Mobile / browser клиент звонит ваш backend, который добавляет sk_live_* ключ и проксирует запрос. Преимущества:

Secret key никогда не покидает ваш сервер
Можно добавить свою бизнес-логику (markup, branding)
Полный контроль над тем, что mobile может делать
Свои логи / трекинг отдельно от NurCore

Magic-link access_token (Consumer flow)

После создания и подтверждения брони пассажир получает на email ссылку с короткоживущим (24 часа) access_token. Token используется вместо X-API-Key для 4 действий:

?access_token=<signed_token>

Действие	Endpoint
Просмотр брони	`GET /bookings/{id}/public?access_token=`
Скачать e-ticket	`GET /bookings/{id}/eticket?access_token=`
Отменить самостоятельно	`POST /bookings/{id}/cancel-consumer?access_token=`
Online check-in	`POST /checkin/consumer?access_token=`

Token bound к одному booking_id — нельзя использовать на другой брони.

Find my trip (восстановление ссылки)

Если пассажир потерял email:

curl -H "X-API-Key: $PUBLISHABLE_KEY" \
     -H "X-Client-Id: $CLIENT_ID" \
     -H "X-Client-Type: consumer_app" \
     "https://api.nurcore.kg/api/v1/bookings/lookup-consumer?pnr=ABC123&email=user@example.com"

API не подтверждает существование брони в ответе (защита от brute-force). Если PNR + email совпадают — ссылка уходит на email.

Rate limit: 3 запроса/мин и 10 запросов/час на IP + дополнительные лимиты на ваш ключ.

Что использовать в каком сценарии

Сценарий	Способ
Backend турагентства бронирует билет	`sk_live_*` (agency)
Mobile-приложение ищет рейсы (через свой BFF)	`sk_live_*` (consumer_app)
Mobile-приложение ищет рейсы напрямую	`pk_live_*` (consumer_app)
Веб-сайт показывает каталог рейсов	`pk_live_*` (consumer_app)
Mobile-приложение создаёт броню от лица пассажира	`sk_live_*` через BFF
Пассажир открывает email с magic-link	`access_token`
Пассажир делает OCI из mobile	`access_token`

On this page