REST · OAuth 2.0 · v1

API для разработчиков

Управляйте хостингом, доменами, мониторингом и кошельком из своего кода. REST, OAuth 2.0, предсказуемые ответы.

Зарегистрировать приложение Открыть документацию Попробовать запрос

OpenAPI JSON YAML Коллекция Postman

205: эндпоинтов
11: без токена
13: прав доступа
17: разделов

Начните за минуту

Первый запрос работает прямо сейчас — регистрация для него не нужна.

1. Публичные данные

Скопируйте и выполните — вернутся реальные цены доменов.

curl https://orax.uz/api/v1/domains/tlds

2. Свои данные

Получите токен по OAuth 2.0 и обращайтесь к своему аккаунту.

curl https://orax.uz/api/v1/services \
  -H "Authorization: Bearer <access_token>"

Что покрывает API

Разделы и число операций считаны из самого справочника — список не может разойтись с тем, что реально работает.

OAuth 2.0

Получение токена: authorization code с PKCE и обмен на access token.

Content

Опубликованные данные: база знаний, блог, отзывы, глоссарий, шаблоны, статус, валюты.

Catalog

Товары, тарифы и категории магазина.

Account

Профиль, настройки отображения, push-устройства, лояльность, рефералы, свои серверы.

Services

Ваши услуги, их состояние, продление и смена тарифа.

Service management

Внутри аккаунта: домены, базы, почта, FTP, SSL, cron, DNS, PHP, логи, shell, SSH-ключи, бэкапы.

Files

Чтение и запись файлов проекта через панель.

Add-ons

Дополнения к услуге (выделенные IP). Цена пересчитывается по курсу при каждом показе.

Domains

Прайс зон, проверка занятости по WHOIS, ваши регистрации и заказ домена.

Monitors

Мониторы доступности: создание, история проверок, удаление.

Security & SLA

Сканы безопасности, оценка услуги, аптайм и расчёт компенсации по SLA.

Orders

Создание, оплата и отмена заказов.

Wallet

Баланс, операции, пополнение и доступные платёжные методы.

AI agent

Запуск AI-агента по проекту, диалоги, аудит действий и инсайты.

MCP

JSON-RPC 2.0 фасад: внешний AI-агент ЧИТАЕТ аккаунт по протоколу MCP.

Embeds

То, что встраивают в страницу, а не вызывают с бэкенда: бейдж аптайма, демо шаблона.

Reseller

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

Авторизация

OAuth 2.0, authorization code. Для мобильных приложений и SPA — обязательно PKCE: в них нельзя зашивать client secret.

0. Зарегистрируйте приложение

Получите client_id и укажите redirect URI. Без этого шага следующие два выполнить не на чем.

Зарегистрировать приложение

1. Отправьте пользователя на страницу согласия

Он увидит, какие права вы запрашиваете, и вернётся на ваш redirect_uri с ?code=…

https://orax.uz/oauth/authorize
  ?client_id=<client_id>
  &redirect_uri=https://your.app/callback
  &response_type=code
  &scope=profile services:read monitors:read
  &state=<random>
  &code_challenge=<base64url(sha256(verifier))>
  &code_challenge_method=S256

2. Обменяйте код на токен

Ответ содержит access token (15 дней) и refresh token (30 дней).

curl -X POST https://orax.uz/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=<client_id> \
  -d redirect_uri=https://your.app/callback \
  -d code_verifier=<verifier> \
  -d code=<code_from_redirect>

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def50200a1b2c3..."
}

3. Обновляйте токен, не переспрашивая пользователя

grant_type=refresh_token на том же адресе. Права выдаются при согласии — токен не может получить право, которое пользователь не одобрил.

Права доступа

Запрашивайте минимум: дашборду аптайма достаточно monitors:read, деньги ему не нужны.

`profile`	Read your Orax profile
`services:read`	View your services
`services:write`	Manage your services (domains, databases, FTP)
`orders:read`	View your orders
`orders:write`	Create and pay orders on your behalf
`wallet:read`	View your wallet balance and transactions
`wallet:write`	Top up your wallet
`ai:read`	View AI agent settings, conversations and project insights
`ai:write`	Run the AI agent and change its settings, files and insights
`domains:read`	View your domain registrations
`domains:write`	Register domains on your behalf (charges your wallet)
`monitors:read`	View your uptime monitors and their history
`monitors:write`	Create and manage your uptime monitors

Список читается из самого сервера авторизации. Административные права третьей стороне не выдаются.

Соглашения

Одинаковые правила во всех эндпоинтах — их достаточно выучить один раз.

Песочница

Приложение можно пометить как песочницу: его токены читают всё, что разрешено правами, а любая запись отклоняется с error=sandbox_read_only. Ничего не купится, пока вы отлаживаетесь.

Деньги — в центах

Биллинг всегда в USD, суммы целые в минорных единицах (usd_cents). Другие валюты — только для отображения.

Списки

Всегда data + meta с page, per_page, total и last_page. per_page ограничен 50.

Ошибки

Поле error — стабильный машинный код, message — переведённый текст для человека. Разбирайте error, не message.

Язык

?lang=uz|ru|en в публичных эндпоинтах отдаёт переводимые поля одной строкой, а не объектом.

Idempotency-Key

Заголовок для запросов, которые тратят деньги. Повтор с тем же ключом в течение суток не спишет второй раз.

Разделы можно отключать

Выключенный раздел отдаёт 404 и в API тоже. Актуальный список приходит в GET /api/v1/me — так приложение прячет вкладку, а не показывает ошибку.

Ответ со списком

{
  "data": [ { "id": 12, "label": "Start", "status": "active" } ],
  "meta": { "page": 1, "per_page": 20, "total": 43, "last_page": 3 }
}

Ответ с ошибкой

{
  "error": "insufficient_funds",
  "message": "На балансе недостаточно средств."
}

Безопасные повторы

Оборвалась сеть — повторите запрос с тем же ключом, второго списания не будет.

curl -X POST https://orax.uz/api/v1/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: 8f14e45f-ea0b-4c1e-9f2d-71c0a3d9b201" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": 7, "domain": "example.uz"}'

Коды ответов

Что действительно нужно обрабатывать.

200 / 201успех; создание возвращает 201
401токен отсутствует или истёк
403у токена нет нужного права
404объект не найден или раздел отключён
409запрос с этим Idempotency-Key уже выполняется
422не прошла валидация или бизнес-правило
429превышен лимит частоты

Лимиты: 90 запросов в минуту на основной API, 60 — на реселлерский, 20 — на проверку домена по WHOIS.

Открытые данные

Без токена и без регистрации.

GET /api/v1/domains/tldsПрайс-лист доменных зон
GET /api/v1/domains/check?domain=Проверка занятости домена по WHOIS
GET /api/v1/kbБаза знаний
GET /api/v1/blogСтатьи блога
GET /api/v1/reviewsОтзывы и средняя оценка
GET /api/v1/glossaryСловарь хостинг-терминов
GET /api/v1/templatesШаблоны сайтов с демо
GET /api/v1/currenciesВалюты и курс к доллару
GET /api/v1/statusСтатус платформы и инциденты

Ваш аккаунт

Токен OAuth 2.0 с нужным правом доступа.

GET /api/v1/meprofile · Профиль, язык, валюта, доступные разделы
GET /api/v1/servicesservices:read · Ваши услуги и их состояние
GET /api/v1/services/{id}/uptimeservices:read · Аптайм, простои и расчёт компенсации
GET /api/v1/services/{id}/securityservices:read · Оценка безопасности услуги
POST /api/v1/domainsdomains:write · Регистрация домена
GET /api/v1/monitorsmonitors:read · Мониторы доступности
POST /api/v1/ordersorders:write · Создание и оплата заказа
GET /api/v1/walletwallet:read · Баланс и история операций

Не только REST

Три отдельных контура для случаев, где обычного REST мало.

Реселлерский API и вебхуки

Отдельный ключ (rsk_…), оптовые цены, провижининг под вашим client_ref. О событиях услуги мы сообщаем подписанным вебхуком — проверяйте подпись, иначе вам сможет написать кто угодно.

Проверка подписи X-Orax-Signature

$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, $yourWebhookSecret);

if (! hash_equals($expected, $_SERVER['HTTP_X_ORAX_SIGNATURE'] ?? '')) {
    http_response_code(403); exit;
}

$event = json_decode($body, true); // service.provisioned | .suspended | .terminated ...

MCP для AI-агентов

JSON-RPC 2.0 по стандарту Model Context Protocol: агент получает список инструментов, отфильтрованный по правам его токена. В первой версии только чтение — деньги и разрушительные действия остаются за человеком.

Адрес для подключения

https://orax.uz/api/v1/mcp

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

Claude Code

claude mcp add --transport http orax https://orax.uz/api/v1/mcp

VS Code

// .vscode/mcp.json
{
  "servers": {
    "orax": { "type": "http", "url": "https://orax.uz/api/v1/mcp" }
  }
}

Расширение Orax ставить не нужно: оба клиента понимают MCP сами. Один адрес — и редактор видит ваш аккаунт.

curl -X POST https://orax.uz/api/v1/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Клиента придётся завести вручную: динамической регистрации (RFC 7591) мы не поддерживаем, поэтому кнопка «добавить в один клик» в некоторых приложениях не сработает. Адрес, вставленный руками, работает везде.

Партнёрам: клиенты пачкой

Отдельная точка входа для партнёров — на вашем же ключе rsk_…, без OAuth. Агент видит услуги всех ваших клиентов сразу: можно отфильтровать по метке клиента, по статусу или по сроку, и каждая строка говорит, покроется ли продление само.

https://orax.uz/api/v1/reseller/mcp

Манифест для каталогов — список инструментов в нём генерируется из самого сервера, поэтому не может устареть:

https://orax.uz/.well-known/mcp/server.json

Встраиваемые блоки

Бейдж аптайма — обычная картинка, без токена и без CORS. Демо шаблона отдаётся в песочнице, его безопасно класть в iframe.

<!-- бейдж аптайма -->
<img src="https://orax.uz/badge/<token>" alt="uptime">

<!-- живое демо шаблона -->
<iframe src="https://orax.uz/templates/12/preview" loading="lazy"></iframe>

Как устроен наш API

Права раздельные

Дашборду аптайма даёте только чтение мониторов — тратить деньги на домены он не сможет.

Секреты не отдаём

Пароли серверов, FTP и баз данных не имеют представления в API. Токен на чтение не станет рутом на вашей машине.

Деньги защищены

Покупки принимают Idempotency-Key: повтор запроса не спишет дважды.

Предсказуемые ответы

Списки всегда с data и meta, отказы возвращают стабильный код ошибки, а не переведённый текст.

Версии и совместимость

Версия в адресе: /api/v1. Внутри v1 мы можем добавлять эндпоинты и новые поля в ответы — ваш код должен спокойно относиться к незнакомым полям. Удаление поля, переименование или смена смысла ответа означают новую версию, а не молчаливое изменение.

Готовы подключиться?

Полное описание всех эндпоинтов, схем и кодов ответов — в справочнике OpenAPI.

Открыть документацию Выбрать хостинг