URnetwork API
URnetwork implementa por completo la especificación de operador del protocolo UR. Protocolo UR ↗
URnetwork is a web-standards VPN marketplace with an emphasis on fast, secure internet everywhere.
The API for URnetwork bootstraps the connect protocol, and is the source of JWTs and other match-making transactions.
Authenticated routes take Authorization: Bearer <token>, where the token is a URnetwork JWT or an API key. The BearerAuth security scheme describes how to get either.
The JWT returned by /auth routes does not have a clientId. The connect protocol requires a JWT with a clientId. Use the /network routes to obtain a JWT with a clientId.
In URnetwork:
- a network name is a globally unique subnet (xyz.ur.network)
- a clientId is a globally unique 16-byte address
- clientIds are equivalent to IPv6, but are expressed as UDID
- clients also have an IPv6 and IPv4 mapped to their clientId
Outside of IP translation like taptun/utun, clients are typically addressed via their clientId.
Unless otherwise specified, time/date strings will be formatted in the Go default 2006-01-02 15: (RFC 3339).
Responses may include additional fields beyond those documented here. Clients should ignore unknown fields (be liberal in what you accept).
Unless a route documents otherwise, an error response has a plain text body. A refusal's body says why. Any other failure is internal: a 500 with a fixed body, whose cause stays in the server's log.
This api process also serves the sim-latency competition under /competition. Those routes are a separate, fail-closed security domain with their own opaque role-scoped tokens, and they are documented in sn/, not here.
Operations marked x-internal: true are not part of the public API: the server-to-server webhooks (payment processors, app stores and the email provider), the operator's provider probe control plane, the admin reports, the operator's own evidence publishing, the validator's head summary upload, the provider work intake (the signed originals the SDK and the independent work authorities post), the acceptance-test routes and the extender directory calls the SDK makes on its own. They stay in this document so the server's route and conformance checks cover them; the public API reference leaves them out.
Authentication
Most routes take a bearer token: Authorization: Bearer <token>. The token is a network JWT or a long-lived urn_ API key. A program without a person at the keyboard gets one from an auth code.
Get a JWT from an auth code
A person signed in to the network creates an auth code at https://ur.io/app/account/settings and gives it to your program. A code works once and expires after 5 minutes.
Exchange the code for a network JWT. This call takes no authentication:
curl -s -X POST https://api. bringyour.com/ auth/ code-login \ -H 'Content-Type: application/json' \ -d '{"auth_code": "<AUTH CODE>"}' The answer is
{"by_jwt": "<JWT>"}, the token the next calls send (as$URNETWORK_below). An unknown, used or expired code answersJWT {"error": {"message": "Invalid auth code."}}.Send the JWT as
Authorization: Bearer <JWT>. For example,POST /network/with aauth-client proxy_configcreates a client and returns its ready-to-use proxy endpoints inproxy_:config_ result curl -s -X POST https://api. bringyour.com/ network/ auth-client \ -H "Authorization: Bearer $URNETWORK_JWT" \ -H 'Content-Type: application/json' \ -d '{"proxy_config": {}}'
Long-lived API keys
The JWT is tied to the session that created the auth code and ends with it. For access that outlives that session, create an API key with the JWT:
curl -s -X POST https:// api. bringyour.com/ account/ api-key \
-H "Authorization: Bearer $URNETWORK_JWT" \
-H 'Content-Type: application/json' \
-d '{"name": "my agent"}'The answer's api_key is a urn_… key, shown only in this answer. Send it wherever a JWT goes: Authorization: Bearer urn_…. GET /account/ lists your keys and POST /account/ with {"id": "<key id>"} revokes one.