Обзор сервиса
Julia (Cyberzone.Julia) — централизованный сервис аутентификации, авторизации, управления профилями пользователей и структурой отделов в экосистеме Cyberzone Dev.
Сервис предоставляет:
- REST API (
/v1) — аутентификация пользователей (OAuth redirect flow, обновление токенов, выход), OIDC/JWKS discovery, управление профилями, медиа, сессиями и отделами. - gRPC API — сервисные вызовы для чтения пользователей и отделов, получения публичного ключа подписи и интроспекции/управления API-ключами.
- Официальные SDK — публичные NuGet-пакеты
Cyberzone.Julia.ContractsиCyberzone.Julia.Authorizationдля .NET и Go-модульgit.cyberzone.dev/cyberzone/julia-go(пре-релизv0.1.0-rc.1) для Go.
Базовые адреса и конвенции
| Параметр | Значение |
|---|---|
| Production Base URL | https://auth.mirea.app/ |
| Версия REST API | /v1 (версионирование в сегменте URL) |
| Формат JSON | snake_case для всех REST-запросов и ответов |
| Схемы аутентификации | Authorization: Bearer <jwt> и X-Api-Key: <key> |
| Discovery | /.well-known/openid-configuration и /.well-known/jwks.json |
/.well-known/* публичны и поддерживают CORS для любых источников — их можно безопасно запрашивать напрямую со сторонних сервисов и клиентов.Формат ошибок
Ошибки бизнес-логики, доступа и ограничений возвращаются в едином JSON-формате и сопровождаются заголовком X-Request-Id для диагностики:
{
"error": "forbidden",
"message": "Access denied"
}
При ошибках валидации входных параметров (обязательные поля, форматы, длины строк) возвращается 400 Bad Request в формате RFC 9457 (ProblemDetails) либо стандартный ErrorResponse.
| HTTP-статус | Типовое значение error | Когда возникает |
|---|---|---|
400 | bad_request или код предметной области | Некорректные параметры запроса, невалидное изображение (invalid_image), нарушения правил отдела |
401 | unauthorized | Отсутствует, истёк или невалиден JWT / API-ключ |
403 | forbidden, insufficient_rank, permission_not_held | Недостаточно прав или старшинства для выполнения операции |
404 | not_found | Ресурс не существует или скрыт от текущего вызывающего |
409 | conflict, already_member | Конфликт состояния (например, повторное добавление участника или конкурентное изменение профиля) |
422 | membership_grants_disabled | Операция отклонена политикой сервиса |
429 | too_many_requests | Превышен лимит запросов (дополнительно возвращается заголовок Retry-After в секундах) |
Ограничения частоты запросов (Rate Limits)
На публичных и ресурсоёмких REST-эндпоинтах действуют лимиты с фиксированным окном:
| Политика | Эндпоинты | Лимит | Партиционирование |
|---|---|---|---|
PublicProfileRead | GET /v1/users, GET /v1/users/{uuid} | 60 запросов / 1 минута | По субъекту (для авторизованных) или по IP клиента (для анонимных) |
ImageUploadPerUser | Загрузка аватаров и баннеров пользователей и отделов | 3 запроса / 5 минут | По субъекту |
При превышении лимита возвращается 429 Too Many Requests с заголовком Retry-After.
Подключение нового приложения
Для интеграции вашего приложения или бэкенд-сервиса потребуется:
- Для веб-приложения с входом пользователей — регистрация
ClientApplication(вы получаетеsourceIdи фиксируете разрешённыйcallback_url). - Для бэкенд-сервиса — выпуск сервисного API-ключа (
cza-svc-...) с минимально необходимым набором прав и, при возможности, списком разрешённых IP-адресов.
Запросить регистрацию клиента или выпуск ключа можно через Telegram @saph1s или по почте [email protected].