# Разработчикам

На URnetwork можно строить три вещи, и у них три разных вида учётных данных.
Выбрать верный — первое решение, и разница не косметическая.

| Что вы строите | С чего начать | Учётные данные |
| --- | --- | --- |
| Приложение или устройство, которое подключается к URnetwork | [SDK](/docs/getting-started-sdk), затем [тур по SDK](/docs/tour-sdk) | JWT аккаунта, который обменивается на JWT с `clientId` |
| Прикладной клиент, использующий TCP, UDP, TLS/DTLS или Direct Sockets через Device | [Сокеты](/docs/socket) | Инициализированный Device с доступным путём соединения |
| Автоматизация в вашей собственной сети | [API оператора](/docs/api) | JWT вашей сети или API-ключ `urn_` |
| Продукт, в который люди входят, допуская его в свою сеть | [Вход через URnetwork (Sign in with URnetwork)](/docs/sign-in-with-urnetwork) | Выданный вам OAuth `client_id` |

Важная граница — **в чьей сети вы действуете**. С SDK и API оператора вы
действуете в своей сети, с учётными данными, которые держите и контролируете
сами. Вход через URnetwork — это человек, допускающий ваше ПО в *свою* сеть:
эти учётные данные никогда не бывают у вас, их выдаёт человек, и он же может
их отозвать.

## SDK

Начните с [установки](/docs/install-sdk), затем откройте обозреватель
[примеров](/docs/examples) с исполняемыми программами на двенадцати языках. Для
каждого языка есть руководство по установке и каталог socket с запускаемыми
интеграциями HTTP-клиентов.

Go SDK, JS/WASM SDK и CGo ABI работают на одном сетевом движке. Десктопные
языковые пакеты оборачивают модуль CGo; Android использует AAR от gomobile, а
Swift — Apple XCFramework. Для JavaScript есть примеры и для Node, и для
браузера, использующие размещённый Device.

[Руководство по сокетам](/docs/socket) объясняет, как использовать соединения
TCP, UDP, TLS/DTLS и Direct Sockets, которые Device держит в пользовательском
пространстве. Приложения могут пользоваться этими сокетами, не устанавливая
системную VPN. DeviceRemote в браузере использует пакетный путь своего
размещённого Device; TUN-интерфейс, которым владеет браузер, ему не нужен.

Раздел [Какой биндинг выбрать](/docs/getting-started-sdk#which-binding)
раскладывает компромиссы бок о бок. Примите это решение до того, как напишете
код: оно определяет вашу модель процессов, а не только синтаксис.

## API оператора

HTTP API, стоящий за URnetwork. Через него проходит бутстрап протокола
`connect`, он выдаёт JWT, которыми аутентифицируются клиенты, и открывает
транзакции подбора (match-making), на которых работает сеть. Каждый маршрут и
каждая схема описаны на [/docs/api](/docs/api), и эта страница сгенерирована
из спецификации.

Его область действия — **ваша** сеть. Название подталкивает к прочтению, будто
он действует на сеть вообще; это не так.

На одном шаге спотыкаются почти все: маршруты `/auth` возвращают JWT **без**
`clientId`, а протоколу `connect` нужен JWT **с** ним. Обменяйте его через
маршруты `/network`. Сеть — это глобально уникальная подсеть
(`xyz.ur.network`); `clientId` — 16-байтовый адрес, эквивалентный адресу IPv6
и выраженный в виде UDID.

## Вход через URnetwork

Позволяет людям допускать ваше приложение или агента в свою приватную сеть,
чтобы оно могло координироваться со всем остальным, что у них там работает.
Это в разработке и ещё не запущено — что существует уже сегодня, смотрите на
[самой странице](/docs/sign-in-with-urnetwork).

[Сервер MCP](/agents) — не четвёртая категория. Это один сервер ресурсов,
доступный по токену входа через URnetwork, и разобранный пример этого
паттерна.

## Границы токенов

Две системы учётных данных подписываются **непересекающимися наборами
ключей**. Это граница безопасности, а не соглашение: токен входа через
URnetwork — не учётные данные платформы, и попытка предъявить его там, где
ожидается JWT платформы, проваливается по построению. Токены доступа OAuth к
тому же привязаны к аудитории: каждый проходит проверку ровно для одного
ресурса и отвергается везде ещё.

Есть один санкционированный переход, и это мост, а не обход: допущенное
приложение обменивает свой токен OAuth на JWT платформы с `clientId`,
ограниченный сетью, в которую его допустили. Обмен — это решение об
авторизации, принимаемое на сервере; ни один токен не проходит проверку в
двух местах.

Если у вас на руках два вида учётных данных и один из них не работает, дело
обычно именно в этом.