IPv4 to IPv6 Proxy API

OpenAPI YAML

This API allows you to manage the configuration of IPv4 to IPv6 proxy servers. These proxies allow you to host a website on an IPv6-only server, and make it accessible to both IPv4 and IPv6 users.

Authentication and authorisation

This API uses our auth service. Credentials for using this API can be obtained from the API Keys section of the control panel. Credentials can be unrestricted, allowing them to manage all proxies for all domains domains on your account, or restricted to individual domains or hostnames.

Authentication for the Proxy API is done using a "Bearer token". Under this method you provide your credentials to the auth service which will return a token which can be used in subsequent requests. See the documentation for the auth service for more details.

API overview

The API allows you to manipulate endpoints. An endpoint is identified by the combination of the following properties:

  • domain – the domain part of the hostname to be proxied (e.g. "example.com").
  • hostname – the host part of the hostname to be proxied (e.g. "www").
  • address – the IPv6 address of the server to which requests are proxied.
  • site – the site in which the proxy server is located, or all if this endpoint exists on all proxy servers.

An endpoint has the following flag:

  • proxy – if true, requests will be proxied using PROXY protocol rather than plain HTTP/HTTPS requests.

domain must correspond to a domain on your customer account. This can be either a registered domain, or a "3rd party domain".

hostname can be the special value @ to indicate that it is the domain name itself that is to be proxied.

address must be an IPv6 address within the Mythic Beasts network.

site should normally use the default value of all indicating that the endpoint is to be configured on all proxy servers.

Fetching endpoints

The API uses hierarchical URLs of the form:

/endpoints
/endpoints/<domain>
/endpoints/<domain>/<hostname>
/endpoints/<domain>/<hostname>/<address>
/endpoints/<domain>/<hostname>/<address>/<site>

All of the above URLs support GET requests, and will return information about all endpoints on the account that match the provided parts of the URL. For example, a GET to:

/endpoints

will return all endpoints to which the API token has access, whereas a GET to:

/endpoints/example.com/www

will return endpoints configured for www.example.com.

Updating endpoints

Endpoints can be created or modified using a PUT request, or deleted using a DELETE request to the following URLs:

/endpoints/<domain>/<hostname>
/endpoints/<domain>/<hostname>/<address>
/endpoints/<domain>/<hostname>/<address>/<site>

A PUT request will replace all endpoints that match the provided parts of the URL. Similarly, a DELETE request will delete all endpoints that match the URL.

In addition, the first URL supports POST requests, which can be used to add additional endpoints without replacing existing ones.

Base URL

The base URL for this service is:

  • https://api.mythic-beasts.com/proxy

The endpoints listed below should be appended to the above URL.

Getting started

To get started using this API:

  1. Create an API key with access to the Proxy API using the customer control panel.

  2. Use your API key credentials to obtain an auth token, as shown in this Auth API example.

  3. Make a request:

curl -D- -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/proxy/endpoints

The above assumes that you have an auth token in the TOKEN environment variable from step (2), and should produce a list endpoints configured on your accoun that the API key has access to.

Endpoints

get /endpoints

https://api.mythic-beasts.com/proxy/endpoints

get /endpoints/{domain}

https://api.mythic-beasts.com/proxy/endpoints/{domain}

get /endpoints/{domain}/{hostname}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}

get /endpoints/{domain}/{hostname}/{address}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}/{address}

get /endpoints/{domain}/{hostname}/{address}/{site}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}/{address}/{site}

Get endpoint information.

This will return all endpoints that match the specified URL path, and which the access token has permission to read.

If the {hostname} URL parameter is not specified (first two URL forms), and there are no matching endpoints, a 200 response with an empty list will be returned.

If the {hostname} URL parameter is specified (last three URL forms), and there are no matching endpoints, the API will return a 404 response.

Responses

CodeDescription
200

List of endpoints

application/json

NameDescription
endpoints array

List of endpoints
domain string

Domain name
hostname string

Host name
address string

IP address
site string

Site
proxy_protocol boolean

Wheter PROXY protocol is enabled or not
Example
{
    "endpoints": [
        {
            "domain": "example.com",
            "hostname": "www",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        },
        {
            "domain": "example.com",
            "hostname": "@",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        }
    ]
}
404

Indicates that there are no endpoints matching the provided URL parameters. Note that this response code is only used if the URL includes the {hostname} part. A query for all endpoints, or all endpoints for a domain will return a 200 response and an empty list if there are no matching endpoints.
400 Bad input
401 Not authenticated
403 Not authorised

put /endpoints/{domain}/{hostname}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}

put /endpoints/{domain}/{hostname}/{address}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}/{address}

put /endpoints/{domain}/{hostname}/{address}/{site}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}/{address}/{site}

Update endpoints

This will create or update endpoints. Any endpoints that match the specified URL path will be replaced with the information provided in the body of the request.

Request Body JSON

NameDescription
endpoints array

(Required) List of endpoints to add.
address string

(Required) IPv6 address of server to proxy requests to.
site string

(Optional) Name of the site to configure proxy servers in, or all for all sites (default: all)
proxy_protocol boolean

(Optional) Whether to use PROXY Protocol when proxying requests (default: false)
Example

application/json

{
    "endpoints": [
        {
            "domain": "example.com",
            "hostname": "www",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        }
    ]
}

Responses

CodeDescription
200

List of endpoints

application/json

NameDescription
endpoints array

List of endpoints
domain string

Domain name
hostname string

Host name
address string

IP address
site string

Site
proxy_protocol boolean

Wheter PROXY protocol is enabled or not
Example
{
    "endpoints": [
        {
            "domain": "example.com",
            "hostname": "www",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        },
        {
            "domain": "example.com",
            "hostname": "@",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        }
    ]
}
400 Bad input
401 Not authenticated
403 Not authorised

post /endpoints/{domain}/{hostname}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}

This creates additional endpoints for the specified domain and hostname. Unlike an equivalent PUT request, existing endpoints will not be replaced.

Request Body JSON

NameDescription
endpoints array

(Required) List of endpoints to add.
address string

(Required) IPv6 address of server to proxy requests to.
site string

(Optional) Name of the site to configure proxy servers in, or all for all sites (default: all)
proxy_protocol boolean

(Optional) Whether to use PROXY Protocol when proxying requests (default: false)
Example

application/json

{
    "endpoints": [
        {
            "domain": "example.com",
            "hostname": "www",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        }
    ]
}

Responses

CodeDescription
200

List of endpoints

application/json

NameDescription
endpoints array

List of endpoints
domain string

Domain name
hostname string

Host name
address string

IP address
site string

Site
proxy_protocol boolean

Wheter PROXY protocol is enabled or not
Example
{
    "endpoints": [
        {
            "domain": "example.com",
            "hostname": "www",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        },
        {
            "domain": "example.com",
            "hostname": "@",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        }
    ]
}
400 Bad input
401 Not authenticated
403 Not authorised

delete /endpoints/{domain}/{hostname}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}

delete /endpoints/{domain}/{hostname}/{address}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}/{address}

delete /endpoints/{domain}/{hostname}/{address}/{site}

https://api.mythic-beasts.com/proxy/endpoints/{domain}/{hostname}/{address}/{site}

This will delete all endpoints matching the URL path.

Responses

CodeDescription
200

List of endpoints

application/json

NameDescription
endpoints array

List of endpoints
domain string

Domain name
hostname string

Host name
address string

IP address
site string

Site
proxy_protocol boolean

Wheter PROXY protocol is enabled or not
Example
{
    "endpoints": [
        {
            "domain": "example.com",
            "hostname": "www",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        },
        {
            "domain": "example.com",
            "hostname": "@",
            "address": "2a00:1098:0:82:1000:3b:1:1",
            "site": "all",
            "proxy_protocol": true
        }
    ]
}
400 Bad input
401 Not authenticated
403 Not authorised

get /sites

https://api.mythic-beasts.com/proxy/sites

Lists the available sites with proxy servers.

Responses

CodeDescription
200

List of sites

application/json

NameDescription
sites array

List of available sites
Example
{
    "sites": [
        "sov",
        "ams",
        "hex"
    ]
}

Common errors

CodeDescription
400

Request cannot be completed due to an error in input.

application/json

NameDescription
error string

Error message
status string

Status message
Example
{
    "error": "1.2.3.4 is not a valid IPv6 address",
    "status": "Error"
}
401

User is not authenticated.

application/json

NameDescription
error string

Error message
Example
{
    "error": "Malformed or missing auth data"
}
403

Not authorised to access this API.

application/json

NameDescription
error string

Error message
Example
{
    "error": "Invalid permits"
}

Support Index

Page contents