Начало работы

Обзор сервиса

Назначение Julia (Cyberzone.Julia), базовые адреса, конвенции API, формат ошибок и лимиты запросов.

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 URLhttps://auth.mirea.app/
Версия REST API/v1 (версионирование в сегменте URL)
Формат JSONsnake_case для всех REST-запросов и ответов
Схемы аутентификацииAuthorization: Bearer <jwt> и X-Api-Key: <key>
Discovery/.well-known/openid-configuration и /.well-known/jwks.json
Discovery-эндпоинты под /.well-known/* публичны и поддерживают CORS для любых источников — их можно безопасно запрашивать напрямую со сторонних сервисов и клиентов.

Формат ошибок

Ошибки бизнес-логики, доступа и ограничений возвращаются в едином JSON-формате и сопровождаются заголовком X-Request-Id для диагностики:

{
  "error": "forbidden",
  "message": "Access denied"
}

При ошибках валидации входных параметров (обязательные поля, форматы, длины строк) возвращается 400 Bad Request в формате RFC 9457 (ProblemDetails) либо стандартный ErrorResponse.

HTTP-статусТиповое значение errorКогда возникает
400bad_request или код предметной областиНекорректные параметры запроса, невалидное изображение (invalid_image), нарушения правил отдела
401unauthorizedОтсутствует, истёк или невалиден JWT / API-ключ
403forbidden, insufficient_rank, permission_not_heldНедостаточно прав или старшинства для выполнения операции
404not_foundРесурс не существует или скрыт от текущего вызывающего
409conflict, already_memberКонфликт состояния (например, повторное добавление участника или конкурентное изменение профиля)
422membership_grants_disabledОперация отклонена политикой сервиса
429too_many_requestsПревышен лимит запросов (дополнительно возвращается заголовок Retry-After в секундах)

Ограничения частоты запросов (Rate Limits)

На публичных и ресурсоёмких REST-эндпоинтах действуют лимиты с фиксированным окном:

ПолитикаЭндпоинтыЛимитПартиционирование
PublicProfileReadGET /v1/users, GET /v1/users/{uuid}60 запросов / 1 минутаПо субъекту (для авторизованных) или по IP клиента (для анонимных)
ImageUploadPerUserЗагрузка аватаров и баннеров пользователей и отделов3 запроса / 5 минутПо субъекту

При превышении лимита возвращается 429 Too Many Requests с заголовком Retry-After.

Подключение нового приложения

Для интеграции вашего приложения или бэкенд-сервиса потребуется:

  1. Для веб-приложения с входом пользователей — регистрация ClientApplication (вы получаете sourceId и фиксируете разрешённый callback_url).
  2. Для бэкенд-сервиса — выпуск сервисного API-ключа (cza-svc-...) с минимально необходимым набором прав и, при возможности, списком разрешённых IP-адресов.

Запросить регистрацию клиента или выпуск ключа можно через Telegram @saph1s или по почте [email protected].

Дальнейшие шаги

Быстрый старт

Пошаговое подключение входа пользователей и проверка JWT в вашем сервисе.

OpenAPI Reference

Изучите все доступные REST-эндпоинты в интерактивном Scalar UI.