FoxyProxy Reseller API Documentation

  1. Home
  2. FoxyProxy Reseller API Documentation

Last update: 2018-04-05

The FoxyProxy Reseller API is a RESTful interface for resellers to resell VPN servers, proxy servers, and customer accounts on those servers. Reselling can be done on your website or within your software product.


Authentication


Reseller


Upon signing up for the reseller service, FoxyProxy will issue you a unique username/password. This username/password is used to authenticate with our REST API using HTTP BASIC authentication. This allows for simpler auth than OAuth2 and is completely stateless and token-less, but at the cost of being inherently insecure since HTTP BASIC is only Base64 encoded without any encryption. Therefore, all API endpoints use HTTPS for encryption.

Reseller’s Users


Your customers, or users, can use this API in limited ways. This is provided so you can write applications for your customer, and he can retrieve proxy information for use within that application. When your users authenticate, they each have their own username/password. The endpoints to which they have access are restricted and discussed further in this document.

Introduction


There are four objects upon which you can operate: nodes, accounts, account history, and node history. A node represents a device on which a VPN server and/or proxy server is running. An account represents a user who can be assigned to one or more nodes (vpn/proxy servers). That account is used to authenticate with and use one or more servers. Account and node history can used to query information about past states of accounts and nodes.

Finally, you should be aware of the concept of your reseller pool. Reseller pool is the list of nodes (or vpn/proxy servers) that you can assign to accounts (users). You may have 1 or 100,000 or any number of nodes in your pool. Currently, reseller pools can be only expanded/reduced by contact with FoxyProxy administrators, not through this API.

You use this API to create accounts for your customers. When first created, an account has no access to nodes (vpn/proxy servers). You must call this API to assign nodes to the account. This process is called leasing and releasing nodes. After leasing, the account can authenticate to the vpn/proxy server running on a node with the username/password you provided to the API at account creation. After releasing, the account can no longer authenticate to the vpn/proxy server on that node, but the node is then available to be leased by other accounts you’ve created. A single account can lease any number of nodes, but they all share the same username/password credentials.

You can also use this API to: list nodes in your reseller pool (both leased and released), deactivate accounts, report on traffic use by account, update accounts (e.g. change password), use account history to view changes to accounts. This is used for billing, but also so you can report changes to your customers if you desire. Node history will be introduced shortly, and will show you changes to nodes, if any, over time. Generally nodes do not change.

Finally, if you have any application that installs onto your customer’s devices, and you want that application to access this API to retrieve vpn/proxy info, that is possible. When creating your customer accounts, create them with the ROLE_USER permission. Without that permission, API use is blocked for your customers. Permissions are discussed further in the accounts section.

API Versioning


The current version of this API is called v1. The API uses the HTTP Content-Type header so that clients can request different API versions. Although all endpoints accept three different Content-Types for your request, you should specify the exact version of the API you want (by using the correct Content-Type header), otherwise you may receive responses that you are not expecting due to API upgrades:

  • application/json: means use the latest version of the API
  • application/vnd.foxyproxy+json: means use the latest version of the API
  • application/vnd.foxyproxy.v1+json: means use exactly v1 of the API, even if there are newer versions
  • Other Content-Types will be added if new API versions are released.
  • Node


    A node represents a device on which a vpn/proxy server is running.

    JSON Example

    {"name":"foobar.ipmatic.io",
    "ipAddress":"999.999.999.999",
    "countryCode":"UK",
    "country":"United Kingdom",
    "city":"London",
    "openVPN": true,
    "IPSec": true,
    "pptp": true,
    "httpProxyPort":51021,
    "sslProxyPort":12167,
    "socks5ProxyPort": 199}

    Note: httpProxyPort, sslProxyPort, socks5ProxyPort, openVPN, IPSec, pptp are optional fields while all others are required. Type of nodes you purchase will dictate which of these fields (or all) are included.

    Properties Description

    name: DNS name of the vpn/proxy server. String. Required. Example: foobar.ipmatic.io
    ipAddress: IP address of the vpn/proxy server. String, maximum 15 characters. Required. Example: 999.999.999.999
    countryCode: 2-character country code in which this node exists. It conforms to ISO 3166-1 alpha-2 with the exception of UK instead of GB. Ireland has its own code, IE. String. Required. Example: UK
    country: English language full-name of the country in which this node lives. String. Required. Example: United Kingdom
    city: English language city in which this node lives. Please note that, due to the inaccuracies of many geo-location databases, this value may not match those reported by the likes of MaxMind, ip2location, and others. This value represents the canonical, or true, location of the device on which this IP address exists. String. Required. Example: London
    openVPN: true/false depending on whether or not openVPN is available on this node
    IPSec: true/false depending on whether or not IPSec VPN is available on this node
    pptp: true/false depending on whether or not PPTP VPN is available on this node
    httpProxyPort: The port on which the proxy server is listening for HTTP and HTTPS connections. Positive integer between 1 and 65535, inclusive. Optional. Example: 51021
    sslProxyPort: The port on which the proxy server is listening for SSL proxy connections. This is NOT the same as the HTTPS protocol. Positive integer between 1 and 65535, inclusive. Optional. Example: 12167
    socks5ProxyPort: The port on which the proxy server is listening for SOCKS proxy connection, if available. Positive integer between 1 and 65535, inclusive. Optional! Example: 199

    Account


    An account represents a user who can be assigned to one or more nodes. The account is used to authenticate with and use vpn/proxy servers on the nodes.

    JSON Example

    {"active":true,
    "username":"ehemingway",
    "password":"YQY4hEGq6a",
    "emailAddresses":["ehemingway@gmail.com","ehemingway@protonmail.com"],
    "resellerCustomId": "a8912B83",
    "roles": ["ROLE_USER", "ROLE_NODE_LEASE", "ROLE_NODE_RELEASE"],
    "created":1522015118000}

    Note: emailAddresses and resellerId are optional fields while all others are required.

    Properties Description

    active: Whether or not this account is active. When true, the associated username/password can authenticate and use the nodes to which it is assigned. When deactivating an account, consider removing its nodes otherwise you will not be able to lease those nodes to other accounts. Boolean. Required. Example: true
    username: Username to authenticate with any nodes assigned to this account. Usernames cannot start with a digit, must be unique, and must be between 6 and 64 characters (inclusive). Non-ASCII characters for usernames are untested and should not be used at this time. String. Required. Example: ehemingway
    password: Unencrypted password to authenticate with any nodes assigned to this account. Passwords must be between 6 and 64 characters (inclusive). Non-ASCII characters for passwords are untested and should not be used at this time. String. Required. Example: YQY4hEGq6a
    emailAddresses: Email addresses associated with this account. Array of strings. Optional! Example: [“ehemingway@gmail.com”,”ehemingway@protonmail.com”]
    resellerCustomId: An id that you can use to associate this account with a user or account in your own system. If your internal IDs are integers, you can use a stringified integer here. String. Optional! Example: a8912B83
    roles: One or more permissions for this account. ROLE_USER identifies the account as reseller’s customer. ROLE_RESELLER identifies the account as as reseller account. Reseller accounts have access to all functions in this API. ROLE_NODE_LEASE is optional. It permits the account to call all endpoints at /api/nodes/lease/ and below, but only for its own username. ROLE_NODE_RELEASE is optional. It permits the account to call /api/nodes/release/ipAddress/{ipAddress} and /api/nodes/release/{username} but only for its own username.
    created: unix timestamp representing when this account was created

    Account History


    An account history tracks changes to an account. This is used for billing, but also so you can track changes to your user accounts.

    JSON Example

    {"propertyName": "active",
    "oldValue":"true",
    "newValue":"false",
    "updatedBy":"jacksmith",
    "when": ""}

    Properties Description

    propertyName: The name of the account property that was changed. Will be one of active, username, password, emailAddresses, or resellerCustomId. String. Required.
    oldValue: The value of the account property before this change. Non-string values, such as Boolean, are stringified (“true”, “false”). String. Required.
    newValue: The value of the account property after this change. Non-string values, such as Boolean, are stringified (“true”, “false”). String. Required.
    updatedBy: The username who made this change. It will either be your reseller username assigned or “admin”. String. Required.
    when: Date/time of the change. String. Required.


    Endpoints and Verbs


    These are the endpoints and verbs used to create, read, update, and delete (CRUD) nodes and accounts.

    Node Endpoints and Verbs

    GET /api/nodes

    When called with ROLE_RESELLER role: returns all nodes assigned to your reseller pool. This includes nodes which are leased and not leased to your customer accounts. Also includes lease info for each node.

    When called with ROLE_USER and ROLE_API roles: returns all nodes leased by the calling customer account, unless the account is inactive in which case 403 Forbidden is returned.

    When called with ROLE_USER role without ROLE_API: 403 Forbidden
    When called with ROLE_USER and ROLE_API and the accounts is inactive: 403 Forbidden

    Returned JSON includes a little more info when called with ROLE_RESELLER role. See examples.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation

    Example Request when called with ROLE_RESELLER role:

    Example Response when called with ROLE_RESELLER role (leasedToAccount is included):

    Example Request when called with ROLE_USER and ROLE_API roles:

    Example Response when called with ROLE_USER and ROLE_API roles (leasedToAccount is excluded):

    GET /api/nodes/{ipAddressOrName}

    When called with ROLE_RESELLER role: Returns the node with the specified IP address or DNS name if it exists and belongs to your reseller pool. If it does not exist or is not in your reseller pool, 404 is returned.

    When called with ROLE_USER and ROLE_API roles: Returns the node with the specified IP address or DNS name if and only if: (1) it exists and belongs to your reseller pool; (2) it is assigned to the account identified by the caller’s credentials; (3) the caller’s account is active

    When called with ROLE_USER role without ROLE_API: 403 Forbidden
    When called with ROLE_USER and ROLE_API and the accounts is inactive: 403 Forbidden

    Returned JSON includes a little more info when called with ROLE_RESELLER role. See examples.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden, 404 Not Found

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Not Found: returned if ipAddress or DNS name does not exist for this reseller or not assigned to calling account

    Example Request when called with ROLE_RESELLER role:

    Example Response when called with ROLE_RESELLER role (leasedToAccount is included):

    Example Request when called with ROLE_USER and ROLE_API roles:

    Example Response when called with ROLE_USER and ROLE_API roles (leasedToAccount is excluded):

    GET /api/nodes/released

    Gets all released (unleased, available) nodes assigned to your reseller pool for all locations. Requires ROLE_RESELLER role.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation

    Example Request:

    Example Response:

    GET /api/nodes/released/count

    Returns a total count of all released (unleased) nodes assigned to your reseller pool, for all locations. Requires the ROLE_RESELLER role.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation

    Example Request:

    Example Response:

    GET /api/nodes/released/location/{countryCode}

    Returns an array of all released (available) nodes in the specified location assigned to your reseller pool. Location is a case-insensitive two-character country code. Requires the ROLE_RESELLER role. Use the /api/nodes/locations endpoint to see all available cities and countries. Note that UK is used for United Kingdom, not GB.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 is not returned for empty results. Instead, an empty JSON array is returned.

    Example Request:

    Example Response:

    GET /api/nodes/released/location/{countryCode}/count

    Returns a count of all released (available) nodes in the specified country code assigned to your reseller pool. Requires the ROLE_RESELLER role. Use the /api/nodes/locations endpoint to see all available cities and countries. Note that UK is used for United Kingdom, not GB.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 is not returned for empty results. Instead, an empty JSON array is returned.

    Example Request:

    Example Response:

    GET /api/nodes/released/location/{countryCode}/{city}

    Returns an array of all released (available) nodes in the specified case-insensitive two-character country code and case-insensitive city assigned to your reseller pool. Be sure to URL encode cities with spaces; e.g. New%20York. Requires the ROLE_RESELLER role. Use the /api/nodes/locations endpoint to see all available cities and countries. Note that UK is used for United Kingdom, not GB.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 is not returned for empty results. Instead, an empty JSON array is returned.

    Example Request:

    GET /api/nodes/released/location/{countryCode}/{city}/count

    Returns a count of all released (available) nodes in the specified case-insensitive two-character country code and case-insensitive city assigned to your reseller pool. Be sure to URL encode cities with spaces; e.g. New%20York. Requires the ROLE_RESELLER role. Use the /api/nodes/locations endpoint to see all available cities and countries. Note that UK is used for United Kingdom, not GB.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 is not returned for empty results. Instead, an empty JSON array is returned.

    Example Request:

    Example Response:

    GET /api/nodes/locations

    Returns all country codes and cities. These include leased and released locations in your reseller pool.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation

    Example Request:

    Example Response:

    GET /api/nodes/leased

    When called with ROLE_RESELLER role: Returns all leased (assigned) nodes assigned to your customer accounts.

    When called with ROLE_USER and ROLE_API roles: Returns all leased (assigned) nodes for this customer accounts.

    When called with ROLE_USER role without ROLE_API: 403 Forbidden
    When called with ROLE_USER and ROLE_API and the account is inactive: 403 Forbidden

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation

    Example Request when called with ROLE_RESELLER role:

    Example Response when called with ROLE_RESELLER role (leasedToAccount is included):

    Example Request when called with ROLE_USER and ROLE_API roles:

    Example Response when called with ROLE_USER and ROLE_API roles (leasedToAccount is excluded):

    GET /api/nodes/leased/count

    When called with ROLE_RESELLER role: Returns a count of all leased (assigned) nodes assigned to your customer accounts.

    When called with ROLE_USER and ROLE_API roles: Returns a count of all leased (assigned) nodes for this customer accounts. Same as GET /api/nodes/leased/{username}/count.

    When called with ROLE_USER role without ROLE_API: 403 Forbidden
    When called with ROLE_USER and ROLE_API and the account is inactive: 403 Forbidden

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation

    Example Request when called with ROLE_RESELLER role:

    Example Response:

    Example Request when called with ROLE_RESELLER role:

    Example Response when called with ROLE_RESELLER role (leasedToAccount is included):

    GET /api/nodes/leased/{username}

    When called with ROLE_RESELLER role: Returns all leased (assigned) nodes assigned to the specified customer account.

    When called with ROLE_USER and ROLE_API roles: Returns all leased (assigned) nodes for the specified customer account (same as ROLE_RESELLER). {username} must match the HTTP BASIC credentials; one account cannot access another account’s info. In order to prevent information leakage, 404 is only returned when role is ROLE_RESELLER.

    When called with ROLE_USER role without ROLE_API: 403 Forbidden
    When called with ROLE_USER and ROLE_API and the account is inactive: 403 Forbidden

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials or the requested account does not match the caller’s ROLE_USER account
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Not Found: returned if no such username/account

    Example Request when called with ROLE_RESELLER:

    Example Response when called with ROLE_RESELLER (leasedToAccount is included):

    Example Request when called with ROLE_USER and ROLE_API:

    Example Response when called with ROLE_USER and ROLE_API: (leasedToAccount is excluded):

    GET /api/nodes/leased/{username}/{count}

    When called with ROLE_RESELLER role: Returns a count of all leased (assigned) nodes assigned to the specified customer account.

    When called with ROLE_USER and ROLE_API roles: Same as GET /api/nodes/leased/count. Returns a count of all leased (assigned) nodes for the specified customer account (same as ROLE_RESELLER). {username} must match the HTTP BASIC credentials; one account cannot access another account’s info. In order to prevent information leakage, 404 is only returned when role is ROLE_RESELLER.

    When called with ROLE_USER role without ROLE_API: 403 Forbidden
    When called with ROLE_USER and ROLE_API and the account is inactive: 403 Forbidden

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials or the requested account does not match the caller’s ROLE_USER account
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Not Found: returned if no such username/account but only if the client has the ROLE_RESELLER role.

    Example Request:

    Example Response:

    PUT /api/nodes/lease/{username}/{count}

    Lease (assign) an arbitrary number of nodes to the specified account, from any locatin and with any IP addresses. Require ROLE_RESELLER or (ROLE_USER, ROLE_API, and ROLE_NODE_LEASE) roles. When called with (ROLE_USER, ROLE_API, ROLE_NODE_LEASE) roles, {username} must match the HTTP BASIC username; one account cannot access another account’s info.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

    400 Bad Request: returned if not enough nodes are available in your reseller pool to fulfill the amount specified in count
    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation or the specified account is inactive
    404 Not Found: returned if no such username/account exists

    Example Request when called with ROLE_RESELLER role:

    Example Response when called with ROLE_RESELLER role:

    Example Request when called with ROLE_USER, ROLE_API, and ROLE_NODE_LEASE roles:

    Example Response when called with ROLE_USER, ROLE_API, and ROLE_NODE_LEASE role (same as when called with ROLE_RESELLER):

    PUT /api/nodes/lease/ipaddress/{ipAddress}/{username}

    Lease (assign) the node with the specified ipAddress to the specified account. Requires the ROLE_RESELLER role or (ROLE_USER and ROLE_API and ROLE_NODE_LEASE) roles. When called with (ROLE_USER and ROLE_API and ROLE_NODE_LEASE) roles, {username} must match the HTTP BASIC credentials; one account cannot lease for another account.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict

    Note: 200 is also returned if the node is already leased to this account.

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Not Found: returned if the username or ipAddress does not exist for this reseller. Also returned if the client is an account (not a reseller; i.e., has ROLE_API and ROLE_NODE_LEASE roles) and this node is already leased to a different account. This prevents information leakage to reseller’s customers.
    409 Conflict: returned if the specified ipAddress is already leased to another account/username, but only if the client has the ROLE_RESELLER role.

    Example Request when called with ROLE_USER, ROLE_API, and ROLE_NODE_LEASE roles:

    Example Response when called with ROLE_USER, ROLE_API, and ROLE_NODE_LEASE roles (same as when called with ROLE_RESELLER):

    Example Response:

    PUT /api/nodes/lease/location/{countryCode}/{username}/{count}

    Lease (assign) nodes in the specified countryCode to the specified account. Country codes are case-insensitive. Use UK for United Kingdom, not GB. Use /api/nodes/locations to get a list of locations for your reseller pool. Requires the ROLE_RESELLER role or (ROLE_USER and ROLE_API and ROLE_NODE_LEASE) roles. When called with (ROLE_USER and ROLE_API and ROLE_NODE_LEASE) roles, {username} must match the HTTP BASIC credentials; one account cannot lease for another account.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

    400 Bad Request: if there are not enough nodes in your reseller pool to fulfill the number in {count}, or unknown country code is specified
    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Not Found: returned if no more nodes are available in this location for your reseller pool

    Example Requests:

    Example Response:

    PUT /api/nodes/lease/location/{countryCode}/{city}/{username}/{count}

    Lease (assign) nodes in the specified countryCode and city to the specified account. Country codes and cities are case-insensitive, but be sure to URL encode cities with spaces; e.g. Los%20Angeles. Use UK for United Kingdom, not GB. Use /api/nodes/locations to get a list of locations for your reseller pool. Requires the ROLE_RESELLER role or (ROLE_USER and ROLE_API and ROLE_NODE_LEASE) roles. When called with (ROLE_USER and ROLE_API and ROLE_NODE_LEASE) roles, {username} must match the HTTP BASIC credentials; one account cannot lease for another account.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

    400 Bad Request: if there are not enough nodes in your reseller pool to fulfill the number in {count}, or unknown country code or unknown city is specified. This includes situtations where you specify a known city and known country, but the city does not belong to that city (e.g. London and DE)
    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Not Found: returned if no more nodes are available in this location for your reseller pool

    Example Requests:

    Example Response:

    PUT /api/nodes/release/ipaddress/{ipAddress}

    Release (unassign) a node to whichever account has it leased. Requires ROLE_RESELLER or (ROLE_USER, ROLE_API, ROLE_NODE_RELEASE) role.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden

    200 OK: If the caller has the ROLE_RESELLER role, 200 is returned if the ipAddress is successfully released. It is also returned if the ipAddress does not exist in your reseller pool OR it exists in your reseller pool but is not currently leased. If the caller has the (ROLE_USER, ROLE_API, ROLE_NODE_RELEASE) roles, 200 is returned if the ipAddress is successfully released. It is also returned if the caller does not have the ipAddress leased (it may be not leased at all or may be leased to a different account owned by the reseller) OR if the ipAddress does not exist in the caller’s reseller’s pool. This prevents information leakage.
    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation; e.g. ROLE_USER and ROLE_API but not ROLE_NODE_RELEASE

    Example Requests:

    Example Response:
    None

    PUT /api/nodes/release/{username}

    Release (unassign) all nodes leased by the specified account. Requires ROLE_RESELLER or (ROLE_USER, ROLE_API, ROLE_NODE_RELEASE) role.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden, 404 Not Found

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Not Found: returned if the username does not exist in your reseller pool

    Example Requests:

    Example Response:
    None

    Account Endpoints and Verbs

    GET /api/accounts/{username}

    Returns an account for the provided username, including the nodes which the account has leased. This can result in large responses when there are many leased nodes. Paging is not yet implemented, but responses should be compressed.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden, 404 Not Found

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Bad Request: returned if the username does not exist for this reseller

    Example Request:

    Example Response:

    POST /api/accounts

    Creates a new account. Usernames cannot start with a digit, must be unique, and must be between 6 and 64 characters (inclusive). Passwords must be between 6 and 64 characters (inclusive). Non-ASCII characters for usernames/passwords are untested and should not be used at this time. New accounts are automatically given the ROLE_USER role. You should decide if you want to grant ROLE_API, ROLE_NODE_LEASE, or ROLE_NODE_RELEASE roles.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden, 405 Bad Request, 409 Conflict

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    405 Bad Request: returned if the username or password does not meet the criteria mentioned earlier
    409 Conflict: returned if the username already exists

    Example Request:

    Example Response:
    none

    PUT /api/accounts/username/{username}

    Updates an existing account. Use this to deactivate/activate an account, change its password, etc. Usernames cannot start with a digit, must be unique, and must be between 6 and 64 characters (inclusive). Passwords must be between 6 and 64 characters (inclusive). Non-ASCII characters for usernames/passwords are untested and should not be used at this time.

    When deactivating an account, the username/password no longer works on the nodes leased by the account. BUT leased nodes are not automatically released. If you want to use them for other accounts, you must release them by calling PUT /api/nodes/username/{username}. This is done so you can reserve nodes for inactive accounts. One use case: you want to offer your customers a grace period after payment fails such that if they pay within a few days, they can still use the same nodes.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden, 404 Not Found, 405 Bad Request, 409 Conflict

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 NotFound: returned if the username does not exist for this reseller
    405 Bad Request: returned if the username or password does not meet the criteria mentioned earlier
    409 Conflict: returned if the username already exists

    Example Request (deactivate an account):

    Example Response:
    none

    Account History Endpoints and Verbs

    GET /api/accounthistory/{username}

    Returns all history for the account, including initial creation of the account, as an array of account history objects.

    Accepts: application/json
    application/vnd.foxyproxy+json
    application/vnd.foxyproxy.v1+json

    Response content type: application/vnd.foxyproxy.api.v1+json
    Response Codes: 200 OK, 401 Unauthorized, 403 Forbidden, 404 Not Found, 405 Bad Request, 409 Conflict

    401 Unauthorized: returned if caller uses incorrect HTTP BASIC credentials
    403 Forbidden: returned if caller does not have sufficient access to perform this operation
    404 Bad Request: returned if the username does not exist for this reseller

    Example Request:

    Example Response (note this is not complete since creation is missing. Example will be updated):

    Billing

    Reseller pool is the pool of nodes from which your accounts lease nodes.

    You are billed on the 1st of every month for the number of nodes that were assigned to your reseller pool during the previous month, pro-rated. You are not billed for the number of accounts or bandwidth used by those accounts. Both accounts (active or inactive) and bandwidth are unlimited.

    For example, if you had 1000 nodes assigned to your reseller pool during a month, you would pay 1000 * monthly_node_price on the 1st of the month, where monthly_node_price is the price assigned to you when your reseller account was created. That value may vary based on country/city, in which case the formula is a little more complicated: (number_of_nodes_in_location_A * monthly_node_price_for_location_A) + number_of_nodes_in_location_B * monthly_node_price_for_location_B), etc

    You are billed even if no bandwidth is used on a node. You are billed even if no account is assigned to a node. This is because we are still paying for servers, connectivity, and our engineers are still ensuring your servers are highly available.

    Billing Grace Period


    We recognize that billing problems sometimes happen; credit card companies can deny a transaction due to suspected fraud or credit/debit limits. We also recognize that a reseller must have impeccable node uptime in order to build customer satisfaction, loyalty, and a good reputation.

    We therefore offer a grace period on failed billed attempts equal to 1 day per month of your active reseller account, up to a maximum of 15 days. After the grace period, we will deactivate your reseller account. All associated accounts will also be deactivated and/or deleted. Your nodes will be dropped/deleted, resold, or offered to other resellers.

    We will gladly negotiate different payment terms for resellers willing to put money into escrow or who pre-pay for nodes, or resellers who build reputation and trust with FoxyProxy over time.

    We will make every reasonable effort to contact you about failed payments. You will be sent 1 email notification per day during your grace period.

    Node Abuse


    We reserve the right to deactivate accounts if they are abusing a node. In such cases, we will make every reasonable effort to notify you first and ask you to contact your customer. However, depending on the type of abuse, we may deactivate the account and notify you afterwards. We will not contact your customers directly without your prior written permission. You can keep this permission on file with us if you would like us to resolve abuse cases directly with your customer all the time. The only means through which we can contact your customers, after given permission, is by the email address(es) you may have provided when creating or updating accounts. If no email addresses were provided, we cannot contact your customers.

    Some examples of node abuse are excessive bandwidth consumption or using nodes for a denial-of-service attack. This is not a complete list. Please also see Section 8 of our terms of service.

    API Abuse


    We reserve the right to deactivate your reseller account if you are abusing the reseller API. We will make every reasonable effort to notify you before deactivation. However, depending on the type of abuse, we may deactivate your reseller account and notify you afterwards. User accounts will not be affected unless there is a billing problem.

    Some examples of API abuse: excessive API hits which cause a denial-of-service. This is not a complete list. Please also see Section 8 of our terms of service.

    Reseller’s Customers


    We will not contact your customers directly without your prior written permission. You can keep this permission on file with us if you would like. The only means through which we can contact your customers, after given permission, is by the email address(es) you may have provided when creating or updating accounts. If no email addresses were provided, we cannot contact your customers.

    Logging of Customer Activity


    We do not log any of your customer’s activity. We do, however, log amount of bandwidth consumed by them. This is reported in the account objects. Please see What information do you log about me? in our FAQ. The FAQ entry applies to your customer accounts.