Operator API

URnetwork API

Version 1.0.0 · 230 operations across 14 groups.OpenAPI-Spezifikation ↗

URnetwork implementiert die Operator-Spezifikation des UR-Protokolls vollständig. UR-Protokoll ↗

Operator-API: deine Automatisierung ruft sie mit einem Netzwerk-JWT oder einem urn_-API-Key auf, und sie wirkt nur auf dein Netzwerk; /network/auth-client stellt das JWT mit clientId aus, das das connect-Protokoll braucht

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:04:05.999999999 -0700 MST (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/api/competition.yml, 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

  1. 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.

  2. Exchange the code for a network JWT. This call takes no authentication:

    Text
    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_JWT below). An unknown, used or expired code answers {"error": {"message": "Invalid auth code."}}.

  3. Send the JWT as Authorization: Bearer <JWT>. For example, POST /network/auth-client with a proxy_config creates a client and returns its ready-to-use proxy endpoints in proxy_config_result:

    Text
    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:

Text
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/api-keys lists your keys and POST /account/api-key/remove with {"id": "<key id>"} revokes one.