POST/network/auth-client
Bearer authauthNetworkClientGain permission to use the connect protocol as the requested clientId, or assign a new clientId.
Two limits apply to creating a top-level client (a client with no source_; top-level clients are the network's peers). Both are enforced only while the deployment enforces concurrent clients, and ancillary clients (with a source_) count toward neither:
- The client limit: 100 active top-level clients. Over it the call answers 200 with
error.and the message "Client limit exceeded."client_ limit_ exceeded - The plan's limit on concurrently connected top-level clients. Over it the call answers 200 with
error.andclient_ limit_ exceeded error.-- a plan limit, not a hard cap.upgrade_ required
An agent that pays over x402 may ask for the terms instead of the error: with the request header X-UR-X402: 1, a refusal with error. answers HTTP 402 with the terms for a Pro month when x402 inline payments are enabled and a price can be quoted, so the agent can pay and retry the same request with PAYMENT-SIGNATURE (x402 v2) or X-PAYMENT (x402 v1) (see /x402). x402 has no header a client sends before it is quoted, so without X-UR-X402: 1 every refusal is the 200 with the error, which the apps, the browser extension and ur.io prompt on. A request that carries a payment is never quoted again.
Two more limits apply to every hosted proxy create (a new client with proxy_config, top-level or ancillary), and these are always enforced, whether or not the deployment enforces concurrent clients:
- The active proxy cap: a free network may hold 5 active hosted proxies and a Pro network 1000. Over it the call answers with
error.and the message "Your plan's limit of 5 active proxies is reached. Remove a proxy to create another, or upgrade to UR Pro for more." A Pro network's message stops after "create another".client_ limit_ exceeded - The create rate: a free network may create 5 hosted proxies a minute and a Pro network 20. A create these limits refuse still counts toward its minute. Over the rate the call answers with
error.and the message "Your plan allows 5 new proxies a minute. Try again in a minute, or upgrade to UR Pro for more." A Pro network's message stops after "Try again in a minute". For a free network both refusals also setclient_ limit_ exceeded error., so they answer the way the plan limit above does: 200 with the error, or HTTP 402 with the terms for a Pro month to a caller that asks for them withupgrade_ required X-UR-X402: 1. Only a new proxy is refused: the network's existing proxies keep working, and removing one makes room for the next. A re-auth of an existing client counts toward neither limit.
A network on an Embed plan has a per-network client allowance that sets both client limits and its active proxy cap.
A provider install (a device that only provides, such as an embedded provider) sets provide_. Creating a top-level client with it is exempt from the 100 top-level client cap and from the concurrent connected client check, because providers do not count toward the plan's client limit. The client is a provider install for its life: it never appears in the network's peer list (/network/), does not receive it, and does not count toward the 100 top-level clients that keep the peer list enabled. Connecting keeps the flag honest: a client that connects with provide intent (X-UR-Provide-Intent: 1) must qualify as a public provider within a grace period, or it takes a normal client slot if one is free, or it is disconnected with the client limit exceeded close. A person's device that also provides declares intent on its connections instead and stays a network peer.
Like roles or a principal the call may not set, a proxy_config the call cannot use is refused before anything is created: the call answers 200 with error. and no client_id or by_. The refusals are:
- "Invalid performance profile: " and the reason, for an invalid
initial_(the rules are on that field), for example "Invalid performance profile: Window size [2, 1] invalid. Max must be >= min"device_ state. performance_ profile - "Invalid location", when
initial_is omitted, or has nodevice_ state locationand nocountry_codethat names a country - "Could not parse lock ip " and the entry, for a
lock_ip_listentry that is neither an IP address nor a subnet
A unique-exit proxy (proxy_) is a hosted proxy whose exit IP no other unique-exit proxy of the network shares (an exact IPv4 address, or an IPv6 /64). It counts toward the active proxy cap and the create rate like any hosted proxy. Its create is refused before anything is created, and without spending the cap or the rate, when:
- the network is not on UR Pro:
error.with the message "Unique exit IPs are a UR Pro feature. Upgrade to UR Pro to create unique-exit proxies." (HTTP 402 with the terms for a Pro month to a caller that asks withupgrade_ required X-UR-X402: 1, like the plan limit above) - the location names one provider (
connect_): "A unique exit picks its own provider: use a country, region, city, group or best available location."location_ id. client_ id unique_is notexit_ replace autoormanual: 'unique_exit_replace must be "auto" or "manual".'- no exit the network does not already hold is available in the location:
error.no_with the message "No unique exit IP is available in this location right now. Try another location, or best available." The created proxy reports its exit inunique_ supply proxy_.config_ result.exit
A re-auth of an existing client (client_id set) ignores proxy_config.
Request bodyshow schema
udid. Optional. If this is given, it must currently exist in the network. Omit this to assign a new client id.
udid. Optional. The source client id when creating an ancillary client id. It must be a client of the caller's network: any other id is refused with error. "Client does not exist.", and nothing is created.
If this is a new device, sets the device name to the description of the device.
If this is a new device, sets the device spec.
Optional. The device's IANA time zone (e.g. America/Chicago). With locale and locales, the campaign emails are placed in the reader's day and written in their language; the server keeps only the network's latest values, never on the client. Every app sends it on each auth-client call; the latest wins. A zone of UTC is ignored.
Optional. The device's BCP 47 locale ("de-DE"), the first of locales. Same rules as time_zone.
Optional. The device's languages, most preferred first, as BCP 47 tags; the campaign emails are written in the first one a template serves. Leave out a language the device cannot name rather than sending a default such as "en". Same rules as time_zone.
Optional. Identity roles assigned to the client at creation, immutable after. Only a network session may set these; when omitted, the session's own roles are inherited. The values have no meaning to the network.
Optional. Identity principal assigned to the client at creation, immutable after. Only a network session may set this; when omitted, the session's own principal is inherited.
Optional, default false. The new client is a provider install: it only provides publicly (public provide mode), like an embedded provider. A new top-level client created with this set is exempt from the 100 top-level client cap and the concurrent connected client check, and is never a network peer (it is not in the peer list, does not receive it, and does not count toward the 100 top-level clients that keep the peer list enabled). The platform judges it as a provider when it connects with provide intent; see /network/. Do not set it for a person's device that also provides. Ignored when client_id or source_ is set.
Optional. Set if the intended use case of the client is cloud proxy. Note local traffic is not allowed on the cloud proxy. A destination must be set via the SDK.
Optional. Allow only the caller's IP subnet to access the proxy.
Optional. Allow only IPs/subnets in the list to access the proxy. The IPs/subnets are converted to the internal IP subnet width. An entry that is neither an IP address nor a subnet is refused (see the endpoint).
Optional. If the client supports ECH, this is not needed, since the HTTP proxy URL will itself be the auth.
Optional. If enabled, a WireGuard configuration will be created for the proxy.
Optional, UR Pro. Pins the proxy to one provider whose exit IP no other unique-exit proxy of the network holds: an exact IPv4 address, or an IPv6 /64. The provider is chosen in initial_'s location (a country, region, city, group, or best available; not a client_id), from healthy, high-quality providers whose exit has been observed in the last 24 hours. Each provider serves at most 3 unique-exit proxies across all networks, and gives each at most half its estimated throughput. The exit IP itself is never reported; proxy_ and /network/ report its place and an opaque exit_id. The refusals are on the endpoint.
Optional, with unique_exit. auto, the default, moves the proxy to a new unique exit when its provider goes offline for more than 120 seconds, stops answering, is excluded for a failed verdict, or starts sharing an exit with another of the network's unique-exit proxies (the last two at once), at most 6 times an hour per proxy and for a tenth of the network's unique-exit proxies an hour. manual keeps the proxy on its failing exit, exit.state replacing, until /network/ moves it: for sessions that must not change IP on their own.
Required when the call creates the client (client_id omitted): without a location, or a country_code that names a country, the call is refused with "Invalid location" (see the endpoint).
Whenever the device is created, it will be set up with this initial state. To configure the device beyond the initial state, the SDK ProxyDevice must be used. Note that the SDK ProxyDevice must reconfigure the device each time it receives a change notice.
Optional. Use one of country_code or location. A two-letter country code such as "de", upper or lower case. Without a location, the call is refused with "Invalid location" (see the endpoint) unless country_code names a country.
Optional. Use one of country_code or location. A location is used as given, ahead of country_code. For no particular location, set connect_ to true.
udid. Optional.
udid. Optional.
udid. Optional.
Optional. True connects through the best available providers, in no particular location.
udid. Optional.
udid. Optional.
udid. Optional.
Marks the location as one of the network's own trusted peers, which egresses under ProvideModeNetwork. It is explicit state: a fixed client id alone does not imply a trusted peer, since it can be a public exit.
Optional. Omitted, the device runs in auto mode. The call is refused (see the endpoint) unless the profile passes the check the device itself applies:
- every
window_sizevalue is at least 0 window_is at leastsize_ max window_size_ min - a fixed window (
window_typequalityorspeed) has awindow_of at least 1, since a window that can hold no provider leaves no routesize_ max
The check covers auto mode too, although auto ignores window_size. Without window_size the device uses its default window, which passes.
Setting this exposes the real source IP to the provider. It has no effect here: the hosted proxy device always runs with direct mode off, because a direct connection would expose the proxy host's address, and with it that the client is hosted and where.
Requires a post-quantum end-to-end encrypted session with each provider. Traffic to a provider waits for its session, and a provider that cannot establish one is skipped, never used without it, so fewer providers may qualify. Unset, the default, the device opens no such session.
Optional. auto, the default, balances traffic across the window types and ignores window_size. quality and speed fix the window type, sized by window_size.
The minimumum number of items in the windows that must be connected via p2p only. Leave 0 for default behavior.
Inclusive, soft limit. When window_, a special fixed size mode is enabled.
Leave 0 to disable (no hard limit)
Clients per source per stream
Leave 0 to disable
Leave 0 to disable (no limit)
Optional. How the proxy device resolves DNS. DoH urls are queried as RFC 8484 wire format, and each must present an IP-SAN certificate when addressed by IP.
A stand-in destination for the platform's plain DNS configuration while the upgrade mux intercepts UDP/TCP :53. It is not an upstream resolver.
Responses3 statuses · show schema
udid
The following proxy URLs and auths may be used:
| URL | Auth |
|---|---|
https:// | no auth needed when the client connects with TLS |
https:// | use HTTP Proxy-Authorization Basic with auth_token as the username (empty pass), or Bearer with auth_token as the bearer token |
http:// | use HTTP Proxy-Authorization Basic with auth_token as the username (empty pass), or Bearer with auth_token as the bearer token |
tcp:// | use auth_token as the username (empty pass) |
wg:// | use wg_ as the full WireGuard config file content, which contains all the necessary keys |
The proxy url will be valid until the client is removed. However, to keep the device and state in memory, the proxy must receive a message at least once per this interval. The SDK ProxyDevice will automatically send a heartbeat with this many seconds. If the proxy is removed from memmory, the next call to the proxy will create a new device set up to the initial_ (if present).
Set for a unique-exit proxy (proxy_): the exit it was created on.
udid. Opaque, stable while the proxy stays on one exit; a new exit (a replacement or a rotate) has a new id. Absent while the proxy has no exit.
The exit's two-letter country code, lower case.
When the proxy moved to this exit.
assigned: the proxy runs on its exit. replacing: the exit failed and the proxy waits for a new one (the replacement caps, or manual replace mode until /network/). no_supply: the exit failed and no other unique exit is available in the location yet; the proxy is retried automatically in auto mode.
With replacing or no_supply, why: offline, unreachable, verdict, collision, cap, manual, or no_supply.
The proxy's unique_, auto or manual.
datetime
udid
udid
udid. The instance_id of the proxy device.
The WireGuard config file for this client.
A hard cap or a rate limit was hit.
A plan limit that UR Pro lifts refused the request: the free plan's limit for concurrent connected top-level clients, its hosted proxy cap or create rate, or a Pro-only feature. Unlike client_ alone this is a plan limit, not a hard cap: surface an upgrade prompt. It is the flag the x402 inline-payment round trip keys off, for a caller that asks for terms with X-UR-X402: 1.
A unique-exit create (proxy_) found no exit in the location that the network does not already hold. Nothing was created, and neither the proxy cap nor the create rate was spent: try another location, or best available.
What the scheme needs to build the payment: the token's EIP-712 domain (name, version) on EVM networks, the facilitator's feePayer (and transactionVersions, when it names them) on Solana.