1 of 72

URnetwork API Docs

Getting Started

Note the API lives at https://api.bringyour.com.

About

BringYour is a web-standards VPN marketplace with an emphasis on fast, secure internet everwhere.

The API for BringYour bootstraps the connect protocol, and is the source of JWTs and other match-making transactions.

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 the BringYour network:

a network name is a globally unique subnet (xyz.bringyour.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.

API reference

Preferences

Set preferences

Hello

Stats

Last 90

Providers overview last 90

Providers

Provider last 90

Auth

Login

Login with password

Verify

Verify send

Password reset

Password set

Network check

Network create

Code create

Code login

Network

Auth client

Remove client

Clients

Provider locations

Find provider locations

Find locations

Find providers

Find providers2

Create provider spec

Feedback

Send feedback

Wallet

Balance

Validate address

Circle init

Circle transfer out

Subscription

Balance

Check balance code

Redeem balance code

Create payment id

Device

Add

Create share code

Share status

Confirm share

Create adopt code

Adopt status

Confirm adopt

Remove adopt code

Associations

Remove association

Set association name

Set name

Set provide

Share code

Qr.png

Adopt code

Qr.png

Connect

Control

Account

Payout wallet

Wallet

Wallets

Remove

Referral code

Transfer

Stats

About

BringYour is a web-standards VPN marketplace with an emphasis on fast, secure internet everwhere.

The API for BringYour bootstraps the connect protocol, and is the source of JWTs and other match-making transactions.

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 the BringYour network:

a network name is a globally unique subnet (xyz.bringyour.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.

get

Get network statistics for the last 90 days. The statistics are updated approximately every 60s.

Responses

200Success

application/json

get

GET /stats/last-90 HTTP/1.1
Host: api.bringyour.com
Accept: */*

200Success

{
  "lookback": 1,
  "created_time": 1,
  "all_transfer_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "all_transfer_summary": 1,
  "all_transfer_summary_rate": 1,
  "all_packets_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "all_packets_summary": 1,
  "all_packets_summary_rate": 1,
  "providers_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "providers_superspeed_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "providers_summary": 1,
  "providers_summary_superspeed": 1,
  "countries_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "countries_summary": 1,
  "regions_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "regions_summary": 1,
  "cities_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "cities_summary": 1,
  "extender_transfer_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "extender_transfer_summary": 1,
  "extender_transfer_summary_rate": 1,
  "extenders_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "extenders_superspeed_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "extenders_summary": 1,
  "extenders_summary_superspeed": 1,
  "networks_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "networks_summary": 1,
  "devices_data": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "devices_summary": 1
}

get

Get the latest status of all clients on this network.

Includes:

Resident status, which is the platform counterpart for the client that handles control commands.
Connections, which are transports from the client to the platform. Note there can be multiple active connections for a single client.
Provide status

Authorizations

Responses

200Success

application/json

get

GET /network/clients HTTP/1.1
Host: api.bringyour.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

{
  "clients": [
    {
      "client_id": "text",
      "device_id": "text",
      "network_id": "text",
      "description": "text",
      "device_name": "text",
      "device_spec": "text",
      "create_time": "text",
      "auth_time": "text",
      "resident": {
        "client_id": "text",
        "instance_id": "text",
        "resident_id": "text",
        "resident_host": "text",
        "resident_service": "text",
        "resident_block": "text",
        "resident_internal_ports": [
          1
        ]
      },
      "provide_mode": 1,
      "connections": [
        {
          "client_id": "text",
          "connection_id": "text",
          "connect_time": "text",
          "disconnect_time": "text",
          "connection_host": "text",
          "connection_service": "text",
          "connection_block": null
        }
      ]
    }
  ]
}

post

Create a new network. A user authority can be associated with at most one network.

Body

user_namestringOptional

user_authstringOptional

email or phone number

auth_jwtstringOptional

auth_jwt_typestring · enumOptionalPossible values:

passwordstringOptional

network_namestringOptional

termsbooleanOptional

user consent to accept terms of service

Responses

200Success

application/json

post

POST /auth/network-create HTTP/1.1
Host: api.bringyour.com
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "user_name": "text",
  "user_auth": "text",
  "auth_jwt": "text",
  "auth_jwt_type": "apple",
  "password": "text",
  "network_name": "text",
  "terms": true
}

200Success

{
  "network": {
    "by_jwt": "text",
    "network_id": "text",
    "network_name": "text"
  },
  "verification_required": {
    "user_auth": "text"
  },
  "error": {
    "message": "text"
  }
}

post

Search for locations and groups that match a query, where there are at least one active provider in good health. The match algorithm accounts for typos and misspelling, and the tolerance can be tuned in the input. Note that a location or group will need to be mapped to an actual provider using /network/find-providers.

Body

querystringOptional

max_distance_fractionnumberOptional

enable_max_distance_fractionbooleanOptional

Responses

200Success

application/json

post

POST /network/find-provider-locations HTTP/1.1
Host: api.bringyour.com
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "query": "text",
  "max_distance_fraction": 1,
  "enable_max_distance_fraction": true
}

200Success

{
  "specs": [
    {
      "location_id": "text",
      "location_group_id": "text",
      "client_id": "text",
      "best_available": true
    }
  ],
  "groups": [
    {
      "location_group_id": "text",
      "name": "text",
      "provider_count": 1,
      "promoted": true,
      "match_distance": 1
    }
  ],
  "locations": [
    {
      "location_id": "text",
      "location_type": "city",
      "name": "text",
      "city": "text",
      "city_location_id": "text",
      "region": "text",
      "region_location_id": "text",
      "country": "text",
      "country_location_id": "text",
      "country_code": "text",
      "provider_count": 1,
      "match_distance": 1
    }
  ],
  "devices": [
    {
      "client_id": "text",
      "device_name": "text"
    }
  ]
}

post

Gain permission to use the connect protocol as the requested clientId, or assign a new clientId. Each network can have at most 128 clientIds. Above that number, new clientId requests will error until one or more existing clientIds are removed.

Authorizations

Body

client_idstringOptional

udid. Optional. If this is given, it must currently exist in the network. Omit this to assign a new client id.

descriptionstringOptional

If this is a new device, sets the device name to the description of the device.

device_specstringOptional

If this is a new device, sets the device spec.

derived_client_idstringOptional

udid. Optional. | The client that the new client is derived from. If this is called with a client jwt, the derived client id is inferred from the jwt.

Responses

200Success

application/json

post

POST /network/auth-client HTTP/1.1
Host: api.bringyour.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "client_id": "text",
  "description": "text",
  "device_spec": "text",
  "derived_client_id": "text"
}

200Success

{
  "by_client_jwt": "text",
  "error": {
    "client_limit_exceeded": true,
    "message": "text"
  }
}

post

Create a new wallet for your network. You can then use it as a payout wallet by posting to /account/payout-wallet.

Authorizations

Body

blockchainstring · enumOptional

The blockchain associated with the address

Possible values:

wallet_addressstringOptional

The "SOL" or "MATIC" wallet address

default_token_typestring · enumOptional

We only support "USDC"

Possible values:

Responses

200Success

application/json

post

POST /account/wallet HTTP/1.1
Host: api.bringyour.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "blockchain": "SOL",
  "wallet_address": "text",
  "default_token_type": "USDC"
}

200Success

{
  "wallet_id": "text"
}