Go service integration
Installation · Integration · Sockets · Messages · Provider · Embed
The app receives a scoped client JWT from its authenticated service backend. Only the backend holds URNETWORK_ and provisions clients through POST /network/. The shared integration contract defines new-client allocation, authorized reissue and the credential boundary.
Client setup
The reusable bootstrap is client.go and go.mod. Import github.com/ and call integration.Open(false) for messaging or integration.Open(true) for sockets. Keep the returned session alive, then call Close() after subscriptions and connections close.
The client modules use Go 1.27.4 and an SDK calendar-version pin. Select a peer/subprotocol-capable SDK version as described in Messages. The sibling programs use a local module replacement for this helper. From go/, build and check the sibling client program:
cd ../messages
go build -o messages-example .
./messages-example --versionThe version check needs no client credentials. In that same messages directory, configure the app and print its assigned client identity:
export URNETWORK_ CLIENT_ JWT= 'scoped-client-jwt-from-your-service'
export URNETWORK_ INSTANCE_ ID= 'persisted-installation-uuid'
./messages-example selfThe JWT must contain its assigned client_id. Generate an installation UUID once, save it in installation storage and reuse it; for example, uuidgen generates one on macOS. The program requires both environment variables and does not persist a new UUID for you. Two messaging terminals need distinct client JWTs/client IDs and distinct persisted instance IDs in the same network. Use Messages for live watch/send commands and Sockets for HTTP/TCP/UDP.
Backend allocator
The server-only executable is main.go and go.mod. Go 1.27.4 is required. This independent server module uses the standard library and does not depend on the URnetwork SDK. Run these commands from go/:
go build -o allocator .
./allocator --self-test--self-test needs no credentials or network; dependency installation and compilation may download build inputs. It checks first allocation versus reissue, invalid service-user/client-ID arguments, private mapping persistence and response parsing.
Configure the backend process and invoke the allocator with a service-user key supplied internally after your service authenticates that user:
umask 077
mkdir -p /absolute/ path/ to/ private-service-state
chmod 700 /absolute/ path/ to/ private-service-state
export URNETWORK_ CLIENT_ MAP= '/ absolute/ path/ to/ private-service-state/ clients.json'
export URNETWORK_ API_ URL= 'https:// api. bringyour.com'
export URNETWORK_ ROOT_ JWT= 'backend-root-jwt-from-your-secret-store'
./allocator user:aliceReplace the example state directory with an absolute, service-owned path. URNETWORK_ and URNETWORK_ are required. URNETWORK_ is optional and defaults to the HTTPS origin shown; explicit localhost HTTP is accepted only for a test/mock endpoint. The allocator appends /network/ itself.
user:alice means the authenticated service user alice. The backend constructs this user: key; it is never a URnetwork client ID or an untrusted request field. The allocator accepts exactly one such key, owns the mapping and accepts no caller-selected client ID. A new key omits client_id and source_ from the request; another invocation for the same key reissues only its stored client_id.
An exclusive per-map lock covers provisioning and an atomic private map update. The mapping stores client IDs, not JWTs. On success the allocator writes JSON containing client_id and by_ to stdout. Capture that result inside the authenticated backend and hand only the scoped credential to the authorized app as URNETWORK_; keep tokens out of ordinary logs. See the shared contract for locking, key validation and configuration details.