Download OpenAPI specification:Download
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:
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 network statistics for the last 90 days. The statistics are updated approximately every 60s.
{- "lookback": 0,
- "created_time": 0,
- "all_transfer_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "all_transfer_summary": 0,
- "all_transfer_summary_rate": 0,
- "all_packets_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "all_packets_summary": 0,
- "all_packets_summary_rate": 0,
- "providers_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "providers_superspeed_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "providers_summary": 0,
- "providers_summary_superspeed": 0,
- "countries_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "countries_summary": 0,
- "regions_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "regions_summary": 0,
- "cities_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "cities_summary": 0,
- "extender_transfer_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "extender_transfer_summary": 0,
- "extender_transfer_summary_rate": 0,
- "extenders_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "extenders_superspeed_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "extenders_summary": 0,
- "extenders_summary_superspeed": 0,
- "networks_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "networks_summary": 0,
- "devices_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "devices_summary": 0
}
Get statistics for all providers in the caller network for the last 90 days. This is meant to answer the top level question of how the providers in a network are performing.
{- "lookback": 0,
- "created_time": "string",
- "uptime": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "transfer_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "payout": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "search_interest": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "contracts": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "clients": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}
}
Get all providers in the caller network. Each provider includes stats from the last 24 hours.
{- "created_time": "string",
- "providers": [
- {
- "client_id": "string",
- "connected": true,
- "connected_events_last_24h": [
- {
- "event_time": "string",
- "connected": true
}
], - "uptime_last_24h": 0,
- "transfer_data_last_24h": 0,
- "payout_last_24h": 0,
- "search_interest_last_24h": 0,
- "contracts_last_24h": 0,
- "clients_last_24h": 0,
- "provide_mode": -1
}
]
}
Get detailed stats on a single provider in the caller network. This is meant to give the user complete visibility over usage.
client_id | string udid |
{- "client_id": "string"
}
{- "lookback": 0,
- "created_time": "string",
- "uptime": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "transfer_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "payout": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "search_interest": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "contracts": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "clients": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}, - "client_details": [
- {
- "client_id": "string",
- "transfer_data": {
- "yyyy-mm-dd1": 0,
- "yyyy-mm-dd2": 0
}
}
]
}
Start a login for a user authority. The user authority may be:
user_auth | string email or phone number |
auth_jwt | string |
auth_jwt_type | string Enum: "apple" "google" |
{- "user_auth": "string",
- "auth_jwt": "string",
- "auth_jwt_type": "apple"
}
{- "user_name": "string",
- "user_auth": "string",
- "auth_allowed": [
- "password"
], - "error": {
- "suggested_user_auth": "password",
- "message": "string"
}, - "network": {
- "by_jwt": "string"
}
}
Password login for email and phone number.
user_auth | string email or phone number |
password | string |
{- "user_auth": "string",
- "password": "string"
}
{- "verification_required": {
- "user_auth": "string"
}, - "network": {
- "by_jwt": "string",
- "name": "string"
}, - "error": {
- "message": "string"
}
}
Verify ownership of email or phone number.
user_auth | string email or phone number |
verify_code | string |
{- "user_auth": "string",
- "verify_code": "string"
}
{- "network": { },
- "error": { }
}
Send verification code to email or phone number.
user_auth | string email or phone number |
{- "user_auth": "string"
}
{- "user_auth": "string"
}
Send password reset code to email or phone number.
user_auth | string email or phone number |
{- "user_auth": "string"
}
{- "user_auth": "string"
}
Check if the network name is available. A new network name must satisfy:
network_name | string |
{- "network_name": "string"
}
{- "available": true
}
Create a new network. A user authority can be associated with at most one network.
user_name | string |
user_auth | string email or phone number |
auth_jwt | string |
auth_jwt_type | string Enum: "apple" "google" |
password | string |
network_name | string |
terms | boolean user consent to accept terms of service |
{- "user_name": "string",
- "user_auth": "string",
- "auth_jwt": "string",
- "auth_jwt_type": "apple",
- "password": "string",
- "network_name": "string",
- "terms": true
}
{- "network": {
- "by_jwt": "string",
- "network_id": "string",
- "network_name": "string"
}, - "verification_required": {
- "user_auth": "string"
}, - "error": {
- "message": "string"
}
}
Create a limited use code (auth code) to share authentication
with connected apps and tools.
The code is tied to the caller session,
and will be expired with any of the caller's sessions.
Currently a code cannot be created for a client JWT
(from /network/auth-client
).
This is a subset of an OAuth flow.
duration_minutes | number |
uses | integer |
{- "duration_minutes": 0,
- "uses": 0
}
{- "auth_code": "string",
- "duration_minutes": 0,
- "uses": 0,
- "error": {
- "auth_code_limit_exceeded": true,
- "message": "string"
}
}
Authenticate with an auth code. The returned session is tied to the session that created the auth code, and will be expired with any of the creator's sessions. This is a subset of an OAuth flow.
auth_code | string |
{- "auth_code": "string"
}
{- "by_jwt": "string",
- "error": {
- "message": "string"
}
}
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.
client_id | string udid. Optional. If this is given, it must currently exist in the network. Omit this to assign a new client id. |
description | string If this is a new device, sets the device name to the description of the device. |
device_spec | string If this is a new device, sets the device spec. |
derived_client_id | string 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. |
{- "client_id": "string",
- "description": "string",
- "device_spec": "string",
- "derived_client_id": "string"
}
{- "by_client_jwt": "string",
- "error": {
- "client_limit_exceeded": true,
- "message": "string"
}
}
Remove a client from the network.
client_id | string udid |
{- "client_id": "string"
}
{- "error": {
- "message": "string"
}
}
Get the latest status of all clients on this network.
Includes:
{- "clients": [
- {
- "client_id": "string",
- "device_id": "string",
- "network_id": "string",
- "description": "string",
- "device_name": "string",
- "device_spec": "string",
- "create_time": "string",
- "auth_time": "string",
- "resident": {
- "client_id": "string",
- "instance_id": "string",
- "resident_id": "string",
- "resident_host": "string",
- "resident_service": "string",
- "resident_block": "string",
- "resident_internal_ports": [
- 0
]
}, - "provide_mode": -1,
- "connections": [
- {
- "client_id": "string",
- "connection_id": "string",
- "connect_time": "string",
- "disconnect_time": "string",
- "connection_host": "string",
- "connection_service": "string",
- "connection_block": null
}
]
}
]
}
Feedback.
object | |
object |
{- "uses": {
- "personal": true,
- "business": true
}, - "needs": {
- "private": true,
- "safe": true,
- "global": true,
- "collaborate": true,
- "app_control": true,
- "block_data_brokers": true,
- "block_ads": true,
- "focus": true,
- "connect_servers": true,
- "run_servers": true,
- "prevent_cyber": true,
- "audit": true,
- "zero_trust": true,
- "visualize": true,
- "other": "string"
}
}
{ }
A list of locations and groups where there are at least one active provider
in good health.
Note that a location or group will need to be mapped to an actual provider
using /network/find-providers
.
{- "specs": [
- {
- "location_id": "string",
- "location_group_id": "string",
- "client_id": null
}
], - "groups": [
- {
- "location_group_id": "string",
- "name": "string",
- "provider_count": 0,
- "promoted": true,
- "match_distance": 0
}
], - "locations": [
- {
- "location_id": "string",
- "location_type": "city",
- "name": "string",
- "city": "string",
- "city_location_id": "string",
- "region": "string",
- "region_location_id": "string",
- "country": "string",
- "country_location_id": "string",
- "country_code": "string",
- "provider_count": 0,
- "match_distance": 0
}
], - "devices": [
- {
- "client_id": "string",
- "device_name": "string"
}
]
}
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
.
query | string |
max_distance_fraction | number |
enable_max_distance_fraction | boolean |
{- "query": "string",
- "max_distance_fraction": 0,
- "enable_max_distance_fraction": true
}
{- "specs": [
- {
- "location_id": "string",
- "location_group_id": "string",
- "client_id": null
}
], - "groups": [
- {
- "location_group_id": "string",
- "name": "string",
- "provider_count": 0,
- "promoted": true,
- "match_distance": 0
}
], - "locations": [
- {
- "location_id": "string",
- "location_type": "city",
- "name": "string",
- "city": "string",
- "city_location_id": "string",
- "region": "string",
- "region_location_id": "string",
- "country": "string",
- "country_location_id": "string",
- "country_code": "string",
- "provider_count": 0,
- "match_distance": 0
}
], - "devices": [
- {
- "client_id": "string",
- "device_name": "string"
}
]
}
Search for locations, groups, and devices that match a query, regardless of whether an providers are active.
query | string |
max_distance_fraction | number |
enable_max_distance_fraction | boolean |
{- "query": "string",
- "max_distance_fraction": 0,
- "enable_max_distance_fraction": true
}
{- "specs": [
- {
- "location_id": "string",
- "location_group_id": "string",
- "client_id": null
}
], - "groups": [
- {
- "location_group_id": "string",
- "name": "string",
- "provider_count": 0,
- "promoted": true,
- "match_distance": 0
}
], - "locations": [
- {
- "location_id": "string",
- "location_type": "city",
- "name": "string",
- "city": "string",
- "city_location_id": "string",
- "region": "string",
- "region_location_id": "string",
- "country": "string",
- "country_location_id": "string",
- "country_code": "string",
- "provider_count": 0,
- "match_distance": 0
}
], - "devices": [
- {
- "client_id": "string",
- "device_name": "string"
}
]
}
Randomly sample providers that for a location or group, which are active and in good health. This allows random iteration by using the exclude input to mark visited providers.
location_id | string udid |
location_group_id | string udid |
count | integer |
exclude_location_ids | Array of strings |
{- "location_id": "string",
- "location_group_id": "string",
- "count": 0,
- "exclude_location_ids": [
- "string"
]
}
{- "client_ids": [
- "string"
]
}
Randomly sample providers for locations, groups, or devices, which are active and in good health. This allows random iteration by using the exclude input to mark visited providers.
Array of objects (ProviderSpec) | |
count | integer |
exclude_client_ids | Array of strings |
{- "specs": [
- {
- "location_id": "string",
- "location_group_id": "string",
- "client_id": null
}
], - "count": 0,
- "exclude_client_ids": [
- "string"
]
}
{- "providers": [
- { }
]
}
Create a spec object for find-providers2
using a description
of the intended use of the network.
query | string description of the intended use of the connection |
{- "query": "string"
}
{- "specs": [
- {
- "location_id": "string",
- "location_group_id": "string",
- "client_id": null
}
]
}
Get the balance for the USDC user custody wallet. The user custody wallet allows BringYour to query the balance, but the user must take actions against the wallet.
{- "wallet_info": {
- "wallet_id": "string",
- "token_id": "string",
- "blockchain": "string",
- "blockchain_symbol": "string",
- "create_date": "string",
- "balance_usdc_nano_cents": 0,
- "address": "string"
}
}
Validate a USDC wallet address on the user custody wallet chain. This can be used to check whether an address can receive a transfer out from the user custody wallet. Please use this before initiating any transfer out to avoid lost funds.
address | string |
{- "address": "string"
}
{- "valid": true
}
Initialize the Circle USDC user self custody wallet. This starts a process that must be completed by the user.
{- "user_token": {
- "user_token": "string",
- "encryption_key": "string"
}, - "challenge_id": "string",
- "error": {
- "message": "string"
}
}
Set up a transfer from the Circle USDC user self custody wallet to an address. This starts a process that must be completed by the user.
to_address | string |
amount_usdc_nano_cents | integer |
terms | boolean user consent to accept terms of transfer |
{- "to_address": "string",
- "amount_usdc_nano_cents": 0,
- "terms": true
}
{- "user_token": {
- "user_token": "string",
- "encryption_key": "string"
}, - "challenge_id": "string",
- "error": {
- "message": "string"
}
}
Get the current subscription status and transfer balance.
{- "balance_byte_count": 0,
- "current_subscription": {
- "subscription_id": "string",
- "store": "string",
- "plan": "string"
}, - "active_transfer_balances": [
- {
- "balance_id": "string",
- "network_id": "string",
- "start_time": "string",
- "end_time": "string",
- "start_balance_byte_count": 0,
- "net_revenue_nano_cents": 0,
- "balance_byte_count": 0
}
], - "pending_payout_usd_nano_cents": 0,
- "wallet_info": {
- "wallet_id": "string",
- "token_id": "string",
- "blockchain": "Polygon",
- "blockchain_symbol": "MATIC",
- "create_date": "string",
- "balance_usdc_nano_cents": 0,
- "address": "string"
}, - "update_time": "string"
}
Check if the balance code is valid.
secret | string |
{- "secret": "string"
}
{- "balance": {
- "start_time": "string",
- "end_time": "string",
- "balance_byte_count": 0
}, - "error": {
- "message": "string"
}
}
Redeem the balance code and add the transfer balance to the caller network.
secret | string |
{- "secret": "string"
}
{- "transfer_balance": {
- "transfer_balance_id": "string",
- "start_time": "string",
- "end_time": "string",
- "balance_byte_count": 0
}, - "error": {
- "message": "string"
}
}
Creates an anonymous payment identifier to be used with purchases. This keeps network information out of the payment processor system. For example in Google Play this is called the "obfuscated account id".
{ }
{- "subscription_payment_id": "string",
- "error": {
- "message": "string"
}
}
Add a device, which can either be owned by the network or shared with the network. The code provided can be either adoption code or a share code. Once a code is added, the device becomes an associated device until confirmation. If the device is a shared device, it will remain an associated device after confirmation.
code | string share code or adopt code |
{- "code": "string"
}
{- "code_type": "share",
- "code": "string",
- "device_name": "string",
- "associated_network_name": "string",
- "client_id": "string",
- "duration_minutes": 0,
- "error": {
- "message": "string"
}
}
Creates a code to adopt a device. The adopt code is valid for a limited time.
device_name | string Name of the device that will be shared to the adopter |
device_spec | string |
{- "device_name": "string",
- "device_spec": "string"
}
{- "adopt_code": "string",
- "adopt_secret": "string",
- "duration_minutes": 0,
- "error": {
- "message": "string"
}
}
The status of the adopt-code device. The status can be one of:
adopt_code | string |
{- "adopt_code": "string"
}
{- "pending": true,
- "associated_network_name": "string",
- "error": {
- "message": "string"
}
}
Confirm the adoption of a device. This must be called from the side that initiates the adoption.
adopt_code | string |
adopt_secret | string |
associated_network_name | string |
{- "adopt_code": "string",
- "adopt_secret": "string",
- "associated_network_name": "string"
}
{- "by_client_jwt": "string",
- "error": {
- "message": "string"
}
}
Remove an adopt code. This must be called from the side that initiates the adoption.
adopt_code | string |
adopt_secret | string |
{- "adopt_code": "string",
- "adopt_secret": "string"
}
{- "error": {
- "message": "string"
}
}
The devices associated with the caller network. Associated devices are:
{- "pending_adoption_devices": [
- {
- "code": "string",
- "device_name": "string",
- "duration_minutes": 0
}
], - "incoming_shared_devices": [
- {
- "pending": true,
- "code": "string",
- "device_name": "string",
- "client_id": "string",
- "network_name": "string"
}
], - "outgoing_shared_devices": [
- {
- "pending": true,
- "code": "string",
- "device_name": "string",
- "client_id": "string",
- "network_name": "string"
}
]
}
Remove a device association. The association can be any of:
code | string |
{- "code": "string"
}
{- "error": {
- "message": "string"
}
}
Set the name of the association.
To set the name of devices owned by the network, use /device/set-name
.
code | string |
device_name | string Name of the device |
{- "code": "string",
- "device_name": "string"
}
{- "error": {
- "message": "string"
}
}
Sets the name of a device owned by the network.
To set the name of devices shared with the network, use /device/set-association-name
.
device_id | string udid |
device_name | string |
{- "device_id": "string",
- "device_name": "string"
}
{- "error": {
- "message": "string"
}
}
Set the provide mode for a device.
client_id | string udid |
ProvideModeDefault-1 (any) or ProvideModeNone0 (any) or ProvideModeNetwork1 (any) or ProvideModeFriendsAndFamily2 (any) or ProvideModePublic3 (any) or ProvideModeStream4 (any) (ProvideMode) |
{- "client_id": "string",
- "provide_mode": -1
}
{- "provide_mode": -1,
- "error": {
- "message": "string"
}
}
Out-of-band control messages for the connect protocol. Blocking request-response control messages need to be handled out-of-band to resolve the possibility of dedlocks in the client sequence.
pack | Array of strings base64 encoded connect protobuf |
{- "pack": [
- "string"
]
}
{- "pack": [
- "string"
], - "error": {
- "message": "string"
}
}