NAV Navbar
enfcli curl Go Java Python

Introduction

BASE URL

https://xaptum.io/api

Welcome to the Xaptum Edge Network Fabric (ENF) API! You can use our API to manage and configure your ENF networks and resources. For a more in-depth explanation of the ENF and its features, check out docs.xaptum.com.

The ENF API is organized around REST. With resource-oriented URLs, JSON-encoded responses, standard HTTP response codes, and straightforward authentication, our API makes it easy to secure and manage your IoT deployments.

Sign up here to get started using the ENF. Please contact us if you have any questions!

Getting Started with the ENF

If you already have an account with Xaptum, then you can get started using the API right away! Simply authenticate using your ENF account credentials.

If not, we're glad to see you're interested. Xaptum's mission is to simplify secure data exchange between Internet-of-Things (IoT) devices and the Cloud. As part of this mission, we're committed to providing a secure way for anyone to manage their IoT devices, whether they number 5 or 500,000. Sign up for a free trial to see how the ENF works for you.

If you're interested in learning more about the ENF after your free trial, don't hesitate to get in touch with us.

Using the API

There are three main ways to use the ENF API.

1. Command-Line-Interface (CLI)

To install the enfcli:

gem install enfcli

Using the enfcli - our CLI tool - you can quickly begin managing your ENF resources. Throughout the API documentation you'll see examples of using the enfcli to perform tasks like creating firewalls, getting rate limits, provisioning networks, and more with a single command.

2. Client libraries

To install the Go client library:

go get github.com/xaptum/go-enf/enf

We've also created client libraries to simplify the process of building powerful integrations with the ENF. We currently have libraries for the following languages:

Let us know if you want (or are interested in writing) a library for a language not listed here!

3. Other languages

The ENF API can be used by any language that supports HTTP and JSON. Our documentation currently includes examples for Python and Java.

Types

Throughout the documentation, there are several parameters or attributes that have "complex" types - think email, timestamp, or ipv6_network. In this section, we describe the underlying JSON Type for each of these types and a formal description of what the type means.

Type JSON Type Format Description
email string "user@domain.com" A valid email address.
ipv4_address string "192.168.100.1" Usual 4-byte format of an IPv4 address
ipv6_address string "2001:470:c19f:21:1c1a:69af:21ec:21e9" IPv6 Address as described in RFC 5952
ipv6_network string "fd00:8f80:8000::9a79:dead:beef/48" A valid /48 or /64 IPv6 prefix assigned to either a ENF domain or network, respectively.
timestamp string "2020-06-23T12:36:09Z" An ISO8601-formatted time.

Authentication

You must replace the YOUR_USERNAME and YOUR_PASSWORD strings with your username and password, respectively.

The ENF API uses access tokens to authenticate requests. This token is obtained by providing the same username and password credentials used to login to the dashboard at xaptum.io. This token expires after one hour.

Usage of the token depends on your chosen tool:

Finally, all API requests must be made over HTTPS.

User Roles

In the ENF, every user belongs to a domain and has an associated USER_ROLE. This USER_ROLE either has the value DOMAIN_ADMIN or DOMAIN_USER, indicating the level of permissions for that user.

Users with the DOMAIN_ADMIN role can view and change anything in their domain. Users with the DOMAIN_USER role can view anything in their domain. Users are discussed further in the Users section.

Authentication Request

To authorize, use this code:

client := enf.NewClient("https://xaptum.io", nil)

const (
  username = "YOUR_USERNAME"
  password = "YOUR_PASSWORD"
)

// Get an authentication token
authReq := &enf.AuthRequest{Username: &username, Password: &password}
authObject, _, _ := client.Auth.Authenticate(context.Background(), authReq)
if err != nil {
  // Handle error
}

// Set the client authentication token
client.ApiToken = *authObject.Token
$ enfcli --host xaptum.io --user <YOUR_USERNAME>
Connecting to 'https://xaptum.io'..... # The command line will now prompt you for your password
Enter Password: <YOUR_PASSWORD>
curl --request POST \
  --url https://xaptum.io/api/xcr/v2/xauth \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"username":"<YOUR_USERNAME>","token":"<YOUR_PASSWORD>"}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"username\":\"<YOUR_USERNAME>\",\"token\":\"<YOUR_PASSWORD>\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/xauth")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .build();

Response response = client.newCall(request).execute();
import requests

url = "https://xaptum.io/api/xcr/v2/xauth"

payload = "{\"username\":\"<YOUR_USERNAME>\",\"token\":\"<YOUR_PASSWORD>\"}"
headers = {
    'content-type': "application/json",
    'accept': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.json())

The authorization commands shown above return the following object:

{
  "data": [
    {
      "username": "<YOUR_USERNAME>",
      "token": "1jadsfk834==jkasdIK9234=jl;99903",
      "user_id": 24,
      "type": "DOMAIN_USER",
      "domain_id": 6,
      "domain_network": "fd00:8f80:0000::/48"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint is used for acquiring an authentication token to use with future requests.

HTTP Request

POST https://xaptum.io/api/xcr/v2/xauth

Request Body

Name Type Description
username string A valid username used at xaptum.io.
token string The password of the account with the given username.

Authentication Object

Name Type Description
username string The same username used in the request.
token string Bearer token used to authenticate API requests.
user_id integer The unique identifier for the user.
type string User role: DOMAIN_ADMIN or DOMAIN_USER. See the User Role section above.
domain_id integer The unique identifier for the domain this user manages.
domain_network ipv6_network The /48 address of the domain managed by this user.

Users

Invites

Invites are how new users are added to the ENF. This section contains information on sending, accepting, deleting, and listing invites. For more information on users, see the User section below.

Invite Object

The Invite Object represents an invite that a domain admin creates to allow a potential user to join their domain. Note that (1) the ENF automatically emails the invite to the user when created and (2) an admin can only invite users to their domain.

Example Invite Object:

{
  "id": 5,
  "created_by": "admin@acme.com",
  "inserted_date": "2019-11-11T20:36:49Z",
  "modified_date": null,
  "domain_id": 6,
  "email": "user@acme.com",
  "invite_token": "abcd1234",
  "name": "Potential Xaptum User",
  "type": "DOMAIN_USER"
}
Attribute Type Description
id integer The unique identifier for the invite.
created_by email Email of the domain admin who sent the invite.
inserted_date timestamp The time that the invite was first sent.
modified_date timestamp The time that the invite was last modified. This will be null if the invite has not been modified.
domain_id integer The unique identifier for the domain associated with this invite.
invite_token string The token that is exchanged by the user to accept an invite.
invited_by string For invites, invited_by is the same as the value of the created_by attribute.
name string The name of the person the invite was sent to.
type string User role: DOMAIN_ADMIN or DOMAIN_USER. See the User Status section above.

Send Invite

// For inviting a DOMAIN_USER
enfcli-admin@acme> user invite-read-only-user --email=user@acme.com --name=Potential Xaptum User

// For inviting a DOMAIN_ADMIN
enfcli-admin@acme> user invite-domain-admin-user --email=admin2@acme.com --name=Potential Xaptum Admin
curl --request POST \
  --url https://xaptum.io/api/xcr/v2/domains/fd00:8f80:0000::/48/invites \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"email":"user@acme.com","full_name":"Xaptum User","user_type":"DOMAIN_USER"}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

domainAddress := "fd00:8f80:8000::/48"

email = "user@acme.com"
fullName = "Potential Xaptum User"
userType = "DOMAIN_USER"

inviteRequest := &SendInviteRequest{
  Email: &email,
  FullName: &fullName,
  UserType: &userType,
}

newInvite, resp, err := client.User.SendNewInvite(context.Background(), domainAddress, inviteRequest)
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"email\":\"user@acme.com\",\"full_name\":\"Xaptum User\",\"user_type\":\"DOMAIN_USER\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains/fd00:8f80:0000::/48/invites")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"email\":\"user@acme.com\",\"full_name\":\"Xaptum User\",\"user_type\":\"DOMAIN_USER\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xcr/v2/domains/fd00:8f80:0000::/48/invites", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "id": 5,
      "created_by": "admin@example.com",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-18T18:51:02Z",
      "version": 1,
      "domain_id": 6,
      "email": "user@acme.com",
      "invite_token": "abcd1234",
      "invited_by": "admin@acme.com",
      "name": "Potential Xaptum User",
      "type": "DOMAIN_USER"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint creates a new invite and sends the invite to the specified email address. If the request is successful, the new invite object will be included in the response.

HTTP Request

POST https://xaptum.io/api/xcr/v2/domains/{domain}/invites

Path Parameters

Name Type Description
domain ipv6_network The address of the ENF domain associated with the invite.

Request Body

Name Type Description
email email Email address that the invite should be sent to.
full_name string The name of the person being invited.
user_type string User role: DOMAIN_ADMIN or DOMAIN_USER. See the User Status section above.

Accept Invite

curl --request POST \
  --url https://xaptum.io/api/xcr/v2/users/invites \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"email":"user@acme.com","code":"abcd1234","name":"User 1","password":"User1234!"}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

email = "user@acme.com"
code = "token1234"
name = "Xaptum User"
password = "User1234!"

acceptInviteRequest := &AcceptInviteRequest{
  Email: &email,
  Code: &code, // Obtained via email.
  Name: &name,
  Password: &password,
}

resp, err := client.User.AcceptInvite(context.Background(), acceptInviteRequest)
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"email\":\"user@acme.com\",\"code\":\"abcd1234\",\"name\":\"User 1\",\"password\":\"User1234!\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/users/invites")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"email\":\"user@acme.com\",\"code\":\"abcd1234\",\"name\":\"User 1\",\"password\":\"User1234!\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xcr/v2/users/invites", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

[]

This API endpoint is used to accept an invite. The code property in the request body is the same code included in the latest invitation email to the provided address. Please note that the simplest way for one to accept an invite is to follow the instructions sent in the invitation email.

HTTP Request

POST https://xaptum.io/api/xcr/v2/users/invites

Request Body

Name Type Description
email email Email address that the invite was sent to.
code string Code sent to the user in the invite email.
name string The chosen name of the new user.
password string The chosen password of the new user.

Resend Invite

enfcli-admin@acme> user resend-user-invite --email=user@acme.com
curl --request PUT \
  --url https://xaptum.io/api/xcr/v2/invites/user@acme.com \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

resp, err := client.User.ResendInvite(context.Background(), "user@acme.com")
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/invites/user@acme.com")
  .put(null)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("PUT", "/api/xcr/v2/invites/user@acme.com", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

[]

This API endpoint resends an invitation with a new code to the provided email address, and invalidates the previous invitation code. Invitations can be resent as many times as needed.

HTTP Request

POST https://xaptum.io/api/xcr/v2/invites/{email}

Path Parameters

Name Type Description
email email The email address to resend the invitation to.

Delete Invite

enfcli-admin@acme> user cancel-user-invite --email=user@acme.com
curl --request DELETE \
  --url https://xaptum.io/api/xcr/v2/invites/user@acme.com \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

resp, err := client.User.DeleteInvite(context.Background(), "user@acme.com")
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/invites/user@acme.com")
  .delete(null)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("DELETE", "/api/xcr/v2/invites/user@acme.com", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

[]

This API endpoint deletes an active invitation to the provided email address.

HTTP Request

DELETE https://xaptum.io/api/xcr/v2/invites/{email}

Path Parameters

Name Type Description
email email The email address to delete the invitation for.

List Active Invites

enfcli-admin@acme> user list-invites
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/domains/fd00:8f80:0000::/48/invites \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

activeInvites, resp, err := client.User.ListInvitesForDomainAddress(context.Background(), "fd00:8f80:8000::/48")
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains/fd00:8f80:0000::/48/invites")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/domains/fd00:8f80:0000::/48/invites", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "id": 5,
      "created_by": "admin@example.com",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-19T17:28:26Z",
      "version": 1,
      "domain_id": 6,
      "email": "user@acme.com",
      "invite_token": "abcd1234",
      "invited_by": "admin@acme.com",
      "name": "Xaptum User",
      "type": "DOMAIN_USER"
    },
    {
      "id": 8,
      "created_by": "admin@example.com",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": null,
      "version": 1,
      "domain_id": 6,
      "email": "user2@acme.com",
      "invite_token": "efgh5678",
      "invited_by": "admin@acme.com",
      "name": "Xaptum User 2",
      "type": "DOMAIN_USER"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint returns a list of all the active invitations to join the provided domain.

HTTP Request

GET https://xaptum.io/api/xcr/v2/domains/{domain}/invites

Path Parameters

Name Type Description
domain ipv6_network The network address of the user's ENF domain.

User

Users are Xaptum's notion of user accounts. Each user belongs to a domain, and each user has one of two roles: DOMAIN_ADMIN or DOMAIN_USER. These are the same roles discussed here. A new user is added by accepting an email invitation sent by an existing user with DOMAIN_ADMIN permissions. For more information on invites, see the Invites section above.

User Status

Each user also has a status of ACTIVE or INACTIVE. ACTIVE users have the normal permissions associated with their role, while INACTIVE users lose their normal permissions, regardless of their role. Only users with the DOMAIN_ADMIN role can activate or deactivate other users.

User Object

The User Object represents a single user on the ENF.

Example User Object:

{
  "user_id": 61,
  "username": "user@acme",
  "description": "A very special user.",
  "full_name": "Xaptum User",
  "last_login": "2019-11-11T20:36:49Z",
  "domain_id": 6,
  "type": "DOMAIN_USER",
  "reset_code": null,
  "reset_time": null,
  "status": "ACTIVE"
}
Attribute Type Description
user_id integer The unique identifier for the user within their domain.
username string The user's username at xaptum.io.
description string A description of the user.
full_name string The full name of the user.
last_login timestamp The time the user last logged in.
domain_id integer The unique identifer for domain this user belongs to.
type string User role: DOMAIN_ADMIN or DOMAIN_USER. See the User Role section above.
reset_code string The code used to reset the user's password. This will be null if the code has not been sent.
reset_time timestamp The time the user last reset their password. This will be null if a reset code has not been sent.
status string User's status: ACTIVE or INACTIVE. See the User Status section above.

List Users

enfcli-admin@acme> user list-users
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/domains/fd00:8f80:0000::/48/users \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

domainAddress := "fd00:8f80:8000::/48"

users, resp, err := client.User.ListUsersForDomainAddress(context.Background(), domainAddress)
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains/fd00:8f80:0000::/48/users")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/domains/fd00:8f80:0000::/48/users", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "user_id": 61,
      "username": "user@acme",
      "description": "A very special user.",
      "full_name": "Xaptum User",
      "last_login": "2019-11-11T20:36:49Z",
      "domain_id": 6,
      "type": "DOMAIN_USER",
      "reset_code": "reset1234",
      "reset_time": "2019-11-11T20:36:49Z",
      "status": "ACTIVE"
    }
  ],
  "pages": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint returns a list of all the users in a domain.

HTTP Request

GET https://xaptum.io/api/xcr/v2/domains/{domain}/users

Path Parameters

Name Type Description
domain ipv6_network The network address of the user's ENF domain.

Update User Status

// For activating a user
enfcli-admin> user activate-user --user-id=61

// For deactivating a user
enfcli-admin> user deactivate-user --user-id=61
curl --request PUT \
  --url https://xaptum.io/api/xcr/v2/users/61/status \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"status":"ACTIVE"}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

userID := 61

status = "ACTIVE"

updateUserStatusRequest := &UpdateUserStatusRequest{
  Status: &status,
}

updatedUser, resp, err := client.User.UpdateUserStatus(context.Background(), userID, updateUserStatusRequest)
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"status\":\"ACTIVE\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/users/61/status")
  .put(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"status\":\"ACTIVE\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("PUT", "/api/xcr/v2/users/61/status", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

[]

This API endpoint updates the status of a user to either ACTIVE or INACTIVE. See the User Status section above for more information.

HTTP Request

PUT https://xaptum.io/api/xcr/v2/users/{user_id}/status

Path Parameters

Name Type Description
user_id integer The unique identifier for the user.

Request Body

Name Type Description
status string The new status of the user: either ACTIVE or INACTIVE.

Reset Password

The process of resetting a user's password has two steps:

  1. Make a request to GET /users/reset with the email address as a query parameter to receive a reset password code via email.
  2. Attach that code in the request body to POST /users/reset to reset the password.

The other way to reset a password is by going through https://xaptum.io/#/reset.

Get Reset Code

curl --request GET \
  --url 'https://xaptum.io/api/xcr/v2/users/reset?email=user@acme.com' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

email := "user@acme.com"

resp, err := client.User.EmailResetPasswordCode(context.Background(), email)
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/users/reset?email=user@acme.com")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/users/reset?email=user@acme.com", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

[]

This API endpoint emails a reset password code to the provided email address. This code will later be used to reset a user's password.

HTTP Request

GET https://xaptum.io/api/xcr/v2/users/reset?email={email}

Query Parameters

Name Type Description
email email The email of the user attempting to reset their password.

Reset Password

curl --request POST \
  --url https://xaptum.io/api/xcr/v2/users/reset \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"email":"user@acme.com","code":"reset1234","pwd":"User1234!"}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

email = "user@acme.com"
code = "reset1234"
password = "User1234!"

resetPasswordRequest := &ResetPasswordRequest{
  Email: &email,
  Code: &code,
  Password: &password,
}

resp, err := client.User.ResetPassword(context.Background(), resetPasswordRequest)
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"email\":\"user@acme.com\",\"code\":\"reset1234\",\"pwd\":\"User1234!\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/users/reset")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"email\":\"user@acme.com\",\"code\":\"reset1234\",\"pwd\":\"User1234!\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xcr/v2/users/reset", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

[]

This API endpoint resets a user's password.

HTTP Request

POST https://xaptum.io/api/xcr/v2/users/reset

Request Body

Name Type Description
email email The email of user attempting to reset their password.
code string The reset code obtained via email.
pwd string The new password of the user.

Network

The methods in this section are all related to networks. The ENF has two types of networks: ENF domains (/48 IPv6 prefixes) and ENF networks (/64 IPv6 prefixes). Users can provision, update, and view ENF domains and ENF networks; users can also limit the traffic to ENF endpoints (/128 IPv6 addresses) within those networks by creating rate limits.

IPv6 Breakdown

An ENF endpoint correspondings to a device in the field. Say, for example, the IPv6 address (created when an endpoint is provisioned via the ENF API) of this devices is fd00:8f80:8000:0000:0000::/128.

Domains

ENF domains represent customer accounts in the ENF. It is identified by a /48 IPv6 prefix and can be divided into /64 subnets called networks. Typically, a customer will have one domain and use networks to segment devices according to function, location, or other policies.

Default policies for settings like endpoint rate limits, firewall rules, and DNS zones can be configured for the domain. These can be overridden for specific networks or endpoints as required.

Domain Status

Domains either have a status of ACTIVE or READY. A status of ACTIVE means that ENF Networks can be provisioned for that domain, while a status of READY means that the ENF Networks can not yet be provisioned. These statuses can be changed through the Update Domain Status method.

Domain Object

Example Domain Object:

{
  "created_by": "admin@acme",
  "inserted_date": "2019-11-11T20:36:49Z",
  "modified_date": "2019-11-13T20:36:49Z",
  "network": "fd00:8f80:8000::/48",
  "name": "admin.acme",
  "status": "ACTIVE"
}

The Domain Object represents an ENF Domain.

Name Type Description
created_by string User who created the domain.
inserted_date timestamp Date and time that the domain was created.
modified_date timestamp Date and time that the domain was last modified. If the domain has not been modified this will be null.
network ipv6_network The /48 address of a domain.
name string Name of the domain.
status string Domain status: ACTIVE or READY

Create a Domain

enfcli-admin@acme> network provision-domain --admin-email=admin@acme.com --admin-name=Xaptum Admin --name=admin.acme
curl --request POST \
  --url https://xaptum.io/api/xcr/v2/domains \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"name":"admin.acme","type":"CUSTOMER_SOURCE","admin_name":"Xaptum Admin","admin_email":"admin@acme.com"}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

name := "admin.acme"
typee := "CUSTOMER_SOURCE" // typee since `type` is a reserved keyword in Go
adminName := "Xaptum Admin"
adminEmail := "admin@acme.com"

createDomainRequest := &DomainRequest{
    Name: &name,
    Type: &typee,
    AdminName: &adminName,
    AdminEmail: &adminEmail,
}

enfNetwork, resp, err := client.Domains.CreateDomain(context.Background(), createDomainRequest)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"name\":\"admin.acme\",\"type\":\"CUSTOMER_SOURCE\",\"admin_name\":\"Xaptum Admin\",\"admin_email\":\"admin@acme.com\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"name\":\"admin.acme\",\"type\":\"CUSTOMER_SOURCE\",\"admin_name\":\"Xaptum Admin\",\"admin_email\":\"admin@acme.com\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xcr/v2/domains", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "created_by": "admin@acme",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z",
      "network": "fd00:8f80:8000::/48",
      "name": "admin.acme",
      "status": "ACTIVE"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint creates a new ENF Domain.

HTTP Request

POST https://xaptum.io/api/xcr/v2/domains

Request Body

Name Type Description
name string Name of the domain.
type string Type of the domain. For now, this will always be CUSTOMER_SOURCE.
admin_name string Name of the admin creating the domain.
admin_email email Email of the admin creating the domain.

Get a Domain

curl --request GET \
  --url https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

domain := "fd00:8f80:8000::/48"

enfDomain, resp, err := client.Domains.GetDomain(context.Background(), domain)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/domains/fd00:8f80:8000::/48", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "created_by": "admin@acme",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z",
      "network": "fd00:8f80:8000::/48",
      "name": "admin.acme",
      "status": "ACTIVE"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endoint gets the information for an ENF Domain. Note that there is no enfcli command for this endpoint.

HTTP Request

GET https://xaptum.io/api/xcr/v2/domains/{domain}

Path Parameters

Name Type Description
domain ipv6_network The /48 address of the domain.

List Domains

enfcli-admin@acme> network list-domains
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/domains \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

domains, resp, err := client.Domains.ListDomains(context.Background())
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/domains", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "created_by": "admin@acme",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z",
      "network": "fd00:8f80:8000::/48",
      "name": "admin.acme",
      "status": "ACTIVE"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint lists all the domains on the ENF.

HTTP Request

GET /domains

Update Domain Status

# Activate a domain (set the status to `ACTIVE`)
enfcli-admin@acme> network activate-domain --network=fd00:8f80:8000::/48

# Deactivate a domain (set the status to `READY`)
enfcli-admin@acme> network deactivate-domain --network=fd00:8f80:8000::/48
curl --request PUT \
  --url https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48/status \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '"ACTIVE"'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

domain := "fd00:8f80:8000::/48"

// For activating a domain...
enfDomain, resp, err := client.Domains.ActivateDomain(context.Background(), domain)
if err != nil {
  // Handle error...
}

// For deactivating a domain...
enfDomain, resp, err = client.Domains.DeactivateDomain(context.Background(), domain)
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "\"ACTIVE\"");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48/status")
  .put(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "\"ACTIVE\""

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("PUT", "/api/xcr/v2/domains/fd00:8f80:8000::/48/status", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "created_by": "admin@acme",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z",
      "network": "fd00:8f80:8000::/48",
      "name": "admin.acme",
      "status": "ACTIVE"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint is used for changing the status of a domain to ACTIVE or READY. See here for more information.

HTTP Request

PUT https://xaptum.io/api/xcr/v2/domains/{domain}/status

Path Parameters

Name Type Description
domain ipv6_network The /48 address of the domain.

Request Body

The request body for this endpoint consists of a single string with a value of ACTIVE or READY, indicating the new status of the domain.

Networks

ENF Networks are /64 IPv6 addresses that represent sections of an ENF domain. ENF networks are the primary way to group devices for easier management. Each ENF endpoint is assigned to one ENF network and various policies like firewall rules and rate limits can be configured for each network.

Network Object

Example Network Object:

{
  "created_by": "xap@admin",
  "inserted_date": "2019-11-11T20:36:49Z",
  "modified_date": "2019-11-13T20:36:49Z",
  "description": "Network for devices #1-#4.",
  "domain": "fd00:8f80:8000::/48",
  "name": "Acme's Test Devices",
  "num_connections": 7,
  "status": "ACTIVE",
  "network": "fd00:8f80:8000:0000::/64"
}

The Network Object represents an ENF network.

Name Type Description
created_by email Email of the admin who created the network.
inserted_date timestamp Date and time that the network was created.
modified_date timestamp Date and time that the network was last modified. If the network was never modified this will be null;
description string Description of the network.
domain ipv6_network The /48 address of the parent domain.
name string Name of the network.
num_connections int Number of endpoints within the network.
status string Network status: ACTIVE or INACTIVE
network ipv6_network The /64 address of the network.

Create Network

enfcli-admin@acme> network provision-network --name="Acme's Test Devices"
curl --request POST \
  --url https://xaptum.io/api/xcr/v2/domains//nws \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"name":"Acme'\''s Test Devices","description":"Network for devices #1-#4."}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

name := "Acme's Test Devices"
description := "Network for devices #1-#4."

createNetworkRequest := &NetworkRequest{
    Name: &name,
    Description: &description
}

newNetwork, resp, err := client.Network.CreateNetwork(context.Background(), createNetworkRequest)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"name\":\"Acme's Test Devices\",\"description\":\"Network for devices #1-#4.\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48/nws")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"name\":\"Acme's Test Devices\",\"description\":\"Network for devices #1-#4.\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xcr/v2/domains/fd00:8f80:8000::/48/nws", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "created_by": "xap@admin",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z",
      "description": "Network for devices #1-#4.",
      "domain": "fd00:8f80:8000::/48",
      "name": "Acme's Test Devices",
      "num_connections": 7,
      "status": "ACTIVE",
      "network": "fd00:8f80:8000:0000::/64"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint creates a new ENF network under the provided domain.

HTTP Request

POST https://xaptum.io/api/xcr/v2/domains/{domain}/nws

Path Parameters

Name Type Description
domain ipv6_network The /48 address of the domain.

Request Body

Name Type Description
name string Name of the network.
description string Description of the network.

Get Network

enfcli-admin@acme> network get-network --network=fd00:8f80:8000:0000::/64
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/nws/fd00:8f80:8000:0000::/64 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

network := "fd00:8f80:8000:0000::/64"

enfNetwork, resp, err := client.Network.GetNetwork(context.Background(), network)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/nws/fd00:8f80:8000:0000::/64")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/nws/fd00:8f80:8000:0000::/64", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "created_by": "xap@admin",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z",
      "description": "Network for devices #1-#4.",
      "domain": "fd00:8f80:8000::/48",
      "name": "Acme's Test Devices",
      "num_connections": 7,
      "status": "ACTIVE",
      "network": "fd00:8f80:8000:0000::/64"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets the details of an ENF network.

HTTP Request

GET https://xaptum.io/api/xcr/v2/nws/{network}

Path Parameters

Name Type Description
network ipv6_network The /64 address of the network.

Update Network

enfcli-admin@acme> network update-network --network=fd00:8f80:8000:0000::/64 --name="Acme's Real Devices" --description="Network for devices #1-#5"
curl --request PUT \
  --url https://xaptum.io/api/xcr/v2/nws/ \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"name":"Acme'\''s Real Devices","description":"Network for devices #1-#5"}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

network := "fd00:8f80:8000:0000::/64"

newName := "Acme's Real Devices"
newDescription := "Network for devices #1-#5"

updateNetworkRequest := &NetworkRequest{
    Name: &newName,
    Description: &newDescription,
}

enfNetwork, resp, err := client.Network.UpdateNetwork(context.Background(), network, updateNetworkRequest)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"name\":\"Acme's Real Devices\",\"description\":\"Network for devices #1-#5\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/nws/")
  .put(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"name\":\"Acme's Real Devices\",\"description\":\"Network for devices #1-#5\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("PUT", "/api/xcr/v2/nws/", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "created_by": "xap@admin",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z",
      "description": "Network for devices #1-#5",
      "domain": "fd00:8f80:8000::/48",
      "name": "Acme's Real Devices",
      "num_connections": 7,
      "status": "ACTIVE",
      "network": "fd00:8f80:8000:0000::/64"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint updates the name or description of an ENF network.

HTTP Request

PUT https://xaptum.io/api/xcr/v2/nws/{network}

Path Parameters

Name Type Description
network ipv6_network The /64 address of the network.

Request Body

Name Type Description
name string The new name of the network.
description string The new description of the network.

Endpoints

ENF Endpoints are /128 IPv6 addresses that represent endpoints on the ENF. In most cases, ENF endpoints represent either an IoT gateway or backend server that is authenticated with the ENF. ENF Endpoints can have firewall and rate limit policies that limit the type and amount of traffic sent by the endpoint, respectively.

Endpoint Object

An example Endpoint object is shown below:

{
  "inserted_date": "2019-11-11T20:36:49Z",
  "modified_date": "2019-11-18T20:36:49Z",
  "domain": "fd00:8f80:8000::/48",
  "network": "fd00:8f80:8000:0000::/64",
  "ipv6": "fd00:8f80:8000:0000:0000::/128",
  "name": "Acme Endpoint #1",
  "state": "ONLINE",
  "ev_source": "TUN",
  "ev_pop_id": 0,
  "ev_instance_id": 0,
  "ev_session_id": 2,
  "ev_timestamp": "2019-11-15T20:36:49Z",
  "ev_asn_org": "Unknown Provider",
  "ev_remote_ip": "123.456.78.91",
  "ev_remote_port": 5000
}

The Endpoint Object represents an ENF endpoint.

Name Type Description
inserted_date timestamp Date and time that the endpoint was created.
modified_date timestamp Date and time that the endpoint was last modified. If the endpoint has not been modified this will be null.
domain ipv6_network The /48 address of the parent domain.
network ipv6_network The /64 address of the parent network.
name string Name of the endpoint.
state string State of the endpoint. Either ONLINE or OFFLINE.
ev_source string Source of the endpoint's last connection.
ev_pop_id integer The ENF PoP that the endpoint last connected to.
ev_instance_id integer The ENF backbone router that the endpoint last connected to.
ev_session_id integer A unique identifier for the endpoint's most recent connection to the ENF. ev_session_id will change each time the endpoint reconnects to the ENF.
ev_timestamp timestamp Date and time of the endpoint's last connection.
ev_asn_org string The name of the lastmile ISP used by the endpoint to connect to the ENF.
ev_remote_ip string The lastmile IP of the endpoint used to connect to the ENF.
ev_remote_port integer The TCP port on the endpoint used to connect to the ENF.

Get Endpoint

enfcli-admin@acme> network get-endpoint --ipv6=fd00:8f80:8000:0000:0000::/128
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

endpoint := "fd00:8f80:8000:0000:0000::/128"

enfEndpoint, resp, err := client.Endpoints.GetEndpoint(context.Background(), endpoint)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above commands returns an HTTP response like this:

{
  "data": [
    {
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-18T20:36:49Z",
      "domain": "fd00:8f80:8000::/48",
      "network": "fd00:8f80:8000:0000::/64",
      "ipv6": "fd00:8f80:8000:0000:0000::/128",
      "name": "Acme Endpoint #1",
      "state": "ONLINE",
      "ev_source": "TUN",
      "ev_pop_id": 0,
      "ev_instance_id": 0,
      "ev_session_id": 2,
      "ev_timestamp": "2019-11-15T20:36:49Z",
      "ev_asn_org": "Unknown Provider",
      "ev_remote_ip": "123.456.78.91",
      "ev_remote_port": 5000
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoints gets the details of an ENF endpoint.

HTTP Request

GET https://xaptum.io/api/xcr/v2/cxns/{endpoint}

Path Parameters

Name Type Description
endpoint ipv6_address The /128 address of the endpoint.

Update Endpoint

enfcli-admin@acme> network update-endpoint --ipv6=fd00:8f80:8000:0000:0000::/128 --name=Endpoint #1 New Name
curl --request PUT \
  --url https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"name":"Endpoint #1 New Name"}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

endpoint := "fd00:8f80:8000:0000::/64"
newName := "Endpoint #1 New Name"

updateEndpointRequest := &EndpointRequest{
    Name: &newName,
}

enfEndpoint, resp, err := client.Endpoint.UpdateEndpoint(context.Background(), endpoint, updateEndpointRequest)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"name\":\"Endpoint #1 New Name\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128")
  .put(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"name\":\"Endpoint #1 New Name\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("PUT", "/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above commands returns an HTTP response like this:

{
  "data": [
    {
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-18T20:36:49Z",
      "domain": "fd00:8f80:8000::/48",
      "network": "fd00:8f80:8000:0000::/64",
      "ipv6": "fd00:8f80:8000:0000:0000::/128",
      "name": "Endpoint #1 New Name",
      "state": "ONLINE",
      "ev_source": "TUN",
      "ev_pop_id": 0,
      "ev_instance_id": 0,
      "ev_session_id": 2,
      "ev_timestamp": "2019-11-15T20:36:49Z",
      "ev_asn_org": "Unknown Provider",
      "ev_remote_ip": "123.456.78.91",
      "ev_remote_port": 5000
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoints updates the name of an ENF endpoint.

HTTP Request

PUT https://xaptum.io/api/xcr/v2/cxns/{endpoint}

Path Parameters

Name Type Description
endpoint ipv6_address The /128 address of the endpoint.

Request Body

Name Type Description
name string The new name of the endpoint.

List Endpoint Events

enfcli-admin@acme> network list-endpoint-events --ipv6=fd00:8f80:8000:0000:0000::/128
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/events \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

endpoint := "fd00:8f80:8000:0000:000::/128"

endpointEvents, resp, err := client.Endpoint.ListEndpointEvents(context.Background(), endpoint)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/events")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/events", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "id": 1000,
      "created_by": "install",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z",
      "network": "fd00:8f80:8000:0000::/64",
      "ipv6": "fd00:8f80:8000:0000:0000::/128",
      "type": "CONNECT",
      "asn_org": "Unknown Provider",
      "remote_ip": "123.456.78.91",
      "remote_port": 10000,
      "source": "TUN",
      "pop_id": 0,
      "instance_id": 0,
      "session_id": 2,
      "timestamp": "2019-11-15T20:36:49Z"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint lists all the events for an ENF endpoint.

HTTP Request

GET /cxns/{endpoint}/events

Path Parameters

Name Type Description
endpoint ipv6_address The /128 address of the endpoint.

Event Object

The Event Object represents an event (also known as a "connection") for an ENF endpoint.

Name Type Description
id string Unique identifer of the event.
created_by string This value can be ignored.
inserted_date timestamp Date and time that the event took place.
network ipv6_network The network in which the event took place.
ipv6 ipv6_address IPv6 address of the endpoint.
type string Type of the event. Either CONNECT or DISCONNECT.
asn_org string Name of the lastmile ISP used by the endpoint to connect to the ENF.
remote_ip string The lastmile IP of the endpoint used to connect to the ENF.
remote_port integer The TCP port on the endpoint used to connect to the ENF.
source string Source of the connection.
pop_id integer Which of Xaptum's PoPs the endpoint connected to.
instance_id integer Which "broker" or "server" inside of the PoP the endpoint is connected to.
session_id integer A unique identifier for the connection.
timestamp timestamp Date and time of the connection.

Rate Limits

Rate limits are used to limit the amount of traffic sent by an ENF endpoint.

Types of Rate Limits

Each endpoint has two rate limits, a byte rate limit and a packet rate limit. These limit the total data in bytes and the number of IPv6 packets sent by the device, respectively.

Each rate limit also includes a configurable burst size that controls how many bytes (or packets) can be sent in one burst. Set this to a value higher than the rate limit to allow short bursts to temporarily exceed the rate limit.

Caps on Rate Limits

Xaptum sets a cap (or max) for each rate limit. The default/current rate limits can be configured anywhere between zero and this max. Contact Xaptum support for information on increasing the max rate limit.

Network and Domain Defaults

Setting a rate limit for each device individually would be a huge pain, so the API supports the notion of default rate limits.

An endpoint with the inherit property set to true inherits the rate limit from its network. A network with the inherit property sets to true inherits the rate limit from its domain. This makes it easy to set a single default or max rate limit policy for the entire domain, but override it as needed for specific networks or even individual devices.

Rate Limit Object

{
  "packets_per_second": 1000000,
  "packets_burst_size": 1000000,
  "bytes_per_second": 1000000000,
  "bytes_burst_size": 1000000000
}

The Rate Limit Object represents a rate limit for ENF domains, networks, and endpoints. For ENF networks and endpoints there is an additional property, inherit, discussed in the section above.

Name Type Description
packets_per_second integer The max number of IPv6 packets an endpoint is allowed to send per second.
packets_burst_size integer The max number of IPv6 packets an endpoint can send out in one burst, even if that number exceeds the packets_per_second.
bytes_per_second integer The max number of bytes allowed an endpoint is allowed to send per second.
bytes_burst_size integer The max number of IPv6 packets an endpoint can send out in one burst, even if that number exceeds the bytes_per_second.

Choosing A Burst Size

In general, we suggest setting the burst size to the same values as the _per_second rate limit. For more information on burst size, see here.

Get Domain Rate Limits

Get Default Domain Rate Limits

Get Default Domain Rate Limits:

enfcli-admin@acme> network list-domain-rate-limits --network=fd00:8f80:8000::/48
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48/ep_rate_limits/default \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

domain := "fd00:8f80:8000::/48"

domainDefaultRateLimits, resp, err := client.Domains.GetDefaultEndpointRateLimits(context.Background(), domain)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48/ep_rate_limits/default")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/domains/fd00:8f80:8000::/48/ep_rate_limits/default", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The command above returns an HTTP response like this:

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets the default rate limits for ENF endpoints within an ENF domain.

HTTP Request

GET https://xaptum.io/api/xcr/v2/domains/{domain}/ep_rate_limits/default

Path Parameters

Name Type Description
domain ipv6_network The /48 address of the domain.

Get Max Domain Rate Limits

Get Max Domain Rate Limits:

enfcli-admin@acme> network list-domain-rate-limits --network=fd00:8f80:8000::/48
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48/ep_rate_limits/max \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

domain := "fd00:8f80:8000::/48"

domainDefaultRateLimits, resp, err := client.Domains.GetMaxEndpointRateLimits(context.Background(), domain)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains/fd00:8f80:8000::/48/ep_rate_limits/max")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/domains/fd00:8f80:8000::/48/ep_rate_limits/max", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The command above returns an HTTP response like this:

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets the max rate limits for ENF endpoints within an ENF domain.

HTTP Request

GET https://xaptum.io/api/xcr/v2/domains/{domain}/ep_rate_limits/max

Path Parameters

Name Type Description
domain ipv6_network The /48 address of the domain.

Set Domain Rate Limits

enfcli-admin@acme> network set-domain-rate-limits --bytes-burst-size=1000000000 --bytes-per-second=1000000000 --limit=default --packets-burst-size=1000000 --packets-per-second=1000000
curl --request POST \
  --url https://xaptum.io/api/xcr/v2/domains//ep_rate_limits/default \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"packets_per_second":1000000,"packets_burst_size":1000000,"bytes_per_second":1000000000,"bytes_burst_size":1000000000}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

domain := "fd00:8f80:8000::/48"

packetsPerSecond := 1000000
packetsBurstSize := 1000000
bytesPerSecond := 100000000
bytesBurstSize := 100000000

newDefaultRateLimits := &DomainRateLimits{
  PacketsPerSecond: &packetsPerSecond,
  PacketsBurstSize: &packetsBurstSize,
  BytesPerSecond: &bytesPerSecond,
  BytesBurstSize: &bytesBurstSize,
}

defaultRateLimits, resp, err := client.Domains.SetDefaultEndpointRateLimits(context.Background(), newDefaultRateLimits, domain)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"packets_per_second\":1000000,\"packets_burst_size\":1000000,\"bytes_per_second\":1000000000,\"bytes_burst_size\":1000000000}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/domains//ep_rate_limits/default")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"packets_per_second\":1000000,\"packets_burst_size\":1000000,\"bytes_per_second\":1000000000,\"bytes_burst_size\":1000000000}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xcr/v2/domains//ep_rate_limits/default", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint sets the default rate limits for all ENF endpoints within an ENF domain.

HTTP Request

PUT https://xaptum.io/api/xcr/v2/domains/{domain}/ep_rate_limits/default

Path Parameters

Name Type Description
domain ipv6_network The /48 address of the domain.

Request Body

Name Type Description
packets_per_second integer Packets per second for endpoints within the domain.
packets_burst_size integer Packets burst size for endpoints within the domain.
bytes_per_second integer Bytes per second for endpoints within the domain.
bytes_burst_size integer Bytes burst size for endpoints within the domain.

Get Network Rate Limits

Get Default Network Rate Limits

Get Default Network Rate Limits:

enfcli-admin@acme> network set-network-rate-limits --bytes-burst-size=1000000000 --bytes-per-second=1000000000 --limit=default --network=fd00:8f80:8000:0000::/64 --packets-burst-size=1000000 --packets-per-second=1000000
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/nws//ep_rate_limits/default \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

network := "fd00:8f80:8000:0000::/64"

networkRateLimits, resp, err := client.Network.GetDefaultRateLimits(context.Background(), network)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/nws//ep_rate_limits/default")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/nws//ep_rate_limits/default", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000,
      "inherit": true
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets the default rate limits for all ENF endpoints within an ENF network.

HTTP Request

GET https://xaptum.io/api/xcr/v2/nws/{network_address}/ep_rate_limits/default

Path Parameters

Name Type Description
network_address ipv6_network The /64 address of the network.

Get Max Network Rate Limits

Get Max Network Rate Limits:

enfcli-admin@acme> network set-network-rate-limits --bytes-burst-size=1000000000 --bytes-per-second=1000000000 --limit=max --network=fd00:8f80:8000:0000::/64 --packets-burst-size=1000000 --packets-per-second=1000000
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/nws/fd00:8f80:8000:0000::/64/ep_rate_limits/max \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

network := "fd00:8f80:8000:0000::/64"

networkRateLimits, resp, err := client.Network.GetMaxRateLimits(context.Background(), network)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/nws/fd00:8f80:8000:0000::/64/ep_rate_limits/max")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/nws/fd00:8f80:8000:0000::/64/ep_rate_limits/max", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000,
      "inherit": true
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets the max rate limits for all ENF endpoints within an ENF network.

HTTP Request

GET https://xaptum.io/api/xcr/v2/nws/{network_address}/ep_rate_limits/max

Path Parameters

Name Type Description
network_address ipv6_network The /64 address of the network.

Set Network Rate Limits

enfcli-admin@acme> network set-network-rate-limits --bytes-burst-size=1000000000 --bytes-per-second=1000000000 --limit=default --network=fd00:8f80:8000:0000::/64 --packets-burst-size=1000000 --packets-per-second=1000000
curl --request POST \
  --url https://xaptum.io/api/xcr/v2/nws/fd00:8f80:8000:0000::/64/ep_rate_limits/default \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"packets_per_second":1000000,"packets_burst_size":1000000,"bytes_per_second":1000000000,"bytes_burst_size":1000000000,"inherit":false}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

network := "fd00:8f80:8000:0000:/64"

packetsPerSecond := 1000000
packetsBurstSize := 1000000
bytesPerSecond := 100000000
bytesBurstSize := 100000000
inherit := false

newNetworkRateLimits := &NetworkRateLimits{
  PacketsPerSecond: &packetsPerSecond,
  PacketsBurstSize: &packetsBurstSize,
  BytesPerSecond: &bytesPerSecond,
  BytesBurstSize: &bytesBurstSize,
  Inherit: &inherit,
}

newNetworkRateLimits, resp, err := client.Network.SetDefaultRateLimits(context.Background(), newNetworkRateLimits, network)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"packets_per_second\":1000000,\"packets_burst_size\":1000000,\"bytes_per_second\":1000000000,\"bytes_burst_size\":1000000000,\"inherit\":false}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/nws/fd00:8f80:8000:0000::/64/ep_rate_limits/default")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"packets_per_second\":1000000,\"packets_burst_size\":1000000,\"bytes_per_second\":1000000000,\"bytes_burst_size\":1000000000,\"inherit\":false}"

headers = {
    'content-type': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xcr/v2/nws/fd00:8f80:8000:0000::/64/ep_rate_limits/default", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000,
      "inherit": true
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint sets the default rate limits for all ENF endpoints within an ENF network.

HTTP Request

POST https://xaptum.io/api/xcr/v2/nws/{network_address}/ep_rate_limits/default

Path Parameters

Name Type Description
network_address ipv6_network The /64 address of the ENF network.

Request Body

Name Type Description
packets_per_second integer Packets per second for ENF endpoints within the network.
packets_burst_size integer Packets burst size for ENF endpoints within the network.
bytes_per_second integer Bytes per second for ENF endpoints within the network.
bytes_burst_size integer Bytes burst size for ENF endpoints within the network.

Get Endpoint Rate Limits

Get Current Endpoint Rate Limits

Get Current Endpoint Rate Limits:

enfcli-admin@acme> network list-endpoint-rate-limits --ipv6=fd00:8f80:8000:0000:0000::/128
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/current \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

endpoint := "fd00:8f80:8000:0000:0000::/128"

endpointRateLimits, resp, err := client.Endpoint.GetCurrentRateLimits(context.Background(), endpoint)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/current")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/current", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The command above returns an HTTP response like this:

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000,
      "inherit": true
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets the current rate limits for an ENF endpoint.

HTTP Request

GET https://xaptum.io/api/xcr/v2/cxns/{endpoint_address}/ep_rate_limits/current

Path Parameters

Name Type Description
endpoint_address ipv6_network The /128 address of the ENF endpoint.

Get Max Endpoint Rate Limits

Get Max Endpoint Rate Limits:

enfcli-admin@acme> network list-endpoint-rate-limits --ipv6=fd00:8f80:8000:0000:0000::/128
curl --request GET \
  --url https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/max \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

endpoint := "fd00:8f80:8000:0000:0000::/128"

endpointRateLimits, resp, err := client.Endpoint.GetMaxRateLimits(context.Background(), endpoint)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/max")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/max", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The command above returns an HTTP response like this:

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000,
      "inherit": true
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets the max rate limits for an ENF endpoint.

HTTP Request

GET https://xaptum.io/api/xcr/v2/cxns/{endpoint_address}/ep_rate_limits/max

Path Parameters

Name Type Description
endpoint_address ipv6_network The /128 address of the ENF endpoint.

Set Endpoint Rate Limits

enfcli-admin@acme> network set-endpoint-rate-limits --bytes-burst-size=1000000000 --bytes-per-second=100000000 --ipv6=fd00:8f80:8000:0000:0000::/128 --limit=current --packets-burst-size=1000000 --packets-per-second-1000000
curl --request POST \
  --url https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/current \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"packets_per_second":1000000,"packets_burst_size":1000000,"bytes_per_second":1000000000,"bytes_burst_size":1000000000,"inherit":false}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

endpoint := "fd00:8f80:8000:0000:0000::/128"

packetsPerSecond := 1000000
packetsBurstSize := 1000000
bytesPerSecond := 100000000
bytesBurstSize := 100000000
inherit := false

newCurrentRateLimits := &EndpointRateLimits{
  PacketsPerSecond: &packetsPerSecond,
  PacketsBurstSize: &packetsBurstSize,
  BytesPerSecond: &bytesPerSecond,
  BytesBurstSize: &bytesBurstSize,
  Inherit: &inherit,
}

newEndpointRateLimits, resp, err := client.Endpoint.SetCurrentRateLimits(context.Background(), newDefaultRateLimits, endpoint)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"packets_per_second\":1000000,\"packets_burst_size\":1000000,\"bytes_per_second\":1000000000,\"bytes_burst_size\":1000000000,\"inherit\":false}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/current")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"packets_per_second\":1000000,\"packets_burst_size\":1000000,\"bytes_per_second\":1000000000,\"bytes_burst_size\":1000000000,\"inherit\":false}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xcr/v2/cxns/fd00:8f80:8000:0000:0000::/128/ep_rate_limits/current", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above commands returns an HTTP response like this::

{
  "data": [
    {
      "packets_per_second": 1000000,
      "packets_burst_size": 1000000,
      "bytes_per_second": 1000000000,
      "bytes_burst_size": 1000000000,
      "inherit": true
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint sets the current rate limits for an ENF endpoint.

HTTP Request

POST https://xaptum.io/api/xcr/v2/cxns/{endpoint_address}/ep_rate_limits/current

Path Parameters

Name Type Description
endpoint_address ipv6_address The /128 address of the ENF endpoint.

Request Body

Name Type Description
packets_per_second integer Packets per second for the ENF endpoint.
packets_burst_size integer Packets burst size for the ENF endpoint.
bytes_per_second integer Bytes per second for the ENF endpoint.
bytes_burst_size integer Bytes burst size for the ENF endpoint.

IAM

The Xaptum Identity and Access Manager (XIAM) provides identity and access management for connection to the Edge Network Fabric (ENF) IPv6 overlay network.

Identities connecting to the ENF are referred to as endpoints and are uniquely identified by their IPv6 addresses.

The IAM API allows interaction with the XIAM to manage access for groups, networks, and endpoints.

IAM Objects

Many of the objects used by the IAM are used only by a single group of REST resources. These objects are defined are defined in the sections that use them - e.g. the Group Object is used by and defined in the IAM Groups section.
The objects listed here are more generic and span multiple sections.

LICENSE Object

Attribute Type Description
endpoint_count number integer
endpoint_limit number integer
creation_timestamp timestamp GMT, millisecond resolution

NEW_LICENSE Object

Attribute Type Description
endpoint_limit number integer

LIST

This is the format of a generic LIST type used by the IAM.
type is a placeholder for the actual datatype to be used.

Attribute Type Description
length number integer - defaults to 100
body type+
previous string ? link to previous resource ?
next string ? link to next resource ?

ERROR

Attribute Type Description
http_error number integer
xiam_error number integer
reason string

Error Codes

IAM Endpoints

Endpoint Objects

The Endpoint Objects are sent and recieved when working with Endpoint REST Resources.

ENDPOINT Object

Attribute Type Description
address ipv6_address
network ipv6_network
active_credentials [CREDENTIAL_DAA | CREDENTIAL_ECDSA] *
creation_timestamp timestamp GMT, millisecond resolution
modification_timestamp timestamp GMT, millisecond resolution

NEW_ENDPOINT_XTT Object

Example: minimal

{
    "ecdsa_credential": {
      "type": "ecdsa_p256",
      "key": "04DBE6BD456E26C1439F4AC641BE54CEBF290F6E19D3C31AD9B593858C043D9F6FAF68ABB33A33B8D6F480F2B0E32540B665A3818068EE5C07D24BFD3AB1AFF870"
    },
    "daa_credential": {
      "type": "daa_lrsw_bn256",
      "pseudonym": "0605FDFFF6859917219B0BF4AAEB7B7D8431BFD358F30703656ECA25D2A2586C6BD20BA8AA17C2700C21F33D5278F57D72CDD6C27A51AE6B28193CD21C1D6BC126",
      "group_id": "3EC837EC4D072E2189EF1F8B288475F02A11EE13722B9EC07A3F1C2E17A4B5D5"
    }
}
Attribute Type Description
daa_credential NEW_CREDENTIAL_DAA
ecdsa_credential NEW_CREDENTIAL_ECDSA
address_request (ipv6_address | ipv6_network) ?

NEW_ENDPOINT_AUTH Object

Example

{
    "ecdsa_credential": {
      "type": "ecdsa_p256",
      "key": "04DBE6BD456E26C1439F4AC641BE54CEBF290F6E19D3C31AD9B593858C043D9F6FAF68ABB33A33B8D6F480F2B0E32540B665A3818068EE5C07D24BFD3AB1AFF870"
    },
    "address_request": {
      "network": "2607:8F80:DEAD:BEEF::/64"
    }
}
Attribute Type Description
ecdsa_credential NEW_CREDENTIAL_ECDSA
address_request ipv6_address | ipv6_network

ENCODED_GROUP_ID Object

base16(GROUP_ID)

CREDENTIAL_DAA Object

Attribute Type Description
type string enum IS(daa_lrsw_bn256)
group_id GROUP_ID
pseudonym string x9.62-encoded curve point
creation_timestamp timestamp GMT, millisecond resolution

NEW_CREDENTIAL_DAA Object

Example

{
    "type": "daa_lrsw_bn256",
    "pseudonym": "0605FDFFF6859917219B0BF4AAEB7B7D8431BFD358F30703656ECA25D2A2586C6BD20BA8AA17C2700C21F33D5278F57D72CDD6C27A51AE6B28193CD21C1D6BC126",
    "group_id": "3EC837EC4D072E2189EF1F8B288475F02A11EE13722B9EC07A3F1C2E17A4B5D5"
}
Attribute Type Description
type string enum IS(daa_lrsw_bn256)
group_id GROUP_ID
pseudonym string x9.62-encoded curve point

CREDENTIAL_ECDSA Object

Attribute Type Description
type string enum IS(ecdsa_p256)
key string x9.62-encoded ecdsa p256 public key
creation_timestamp timestamp GMT, millisecond resolution

NEW_CREDENTIAL_ECDSA Object

Example

{
    "type": "ecdsa_p256",
    "key": "04DBE6BD456E26C1439F4AC641BE54CEBF290F6E19D3C31AD9B593858C043D9F6FAF68ABB33A33B8D6F480F2B0E32540B665A3818068EE5C07D24BFD3AB1AFF870"
}
Attribute Type Description
type string enum IS(ecdsa_p256)
key string x9.62-encoded ecdsa p256 public key

Query Endpoints

Queries return a list of ENDPOINT Objects

HTTP Request

GET https://xaptum.io/api/xiam/v1/endpoints/?{query-string}

Query Parameters

Name Type Description
limit number integer
start ipv6_address
group string Encoded Group ID
network ipv6_network

Update endpoints by query

POST requests to update endpoints return an ENDPOINT Object

HTTP Request

GET https://xaptum.io/api/xiam/v1/endpoints/?{query-string}

Query Parameters are the same as for the Query Endpoints

Get Endpoint Details

Returns an ENDPOINT Object

HTTP Request

GET https://xaptum.io/api/xiam/v1/endpoints/{ipv6_address}

Path Parameters

Name Type Description
ipv6_address string ipv6_address

Get Credentials for an Endpoint

Responds with a list of either CREDENTIAL_DAA or CREDENTIAL_ECDSA objects.

HTTP Request

GET https://xaptum.io/api/xiam/v1/endpoints/{ipv6_address}/credentials?{credential-type}

Path Parameters

Name Type Description
ipv6_address string ipv6_address

Query Parameters

Name Type Description
credential-type string daa or ecdsa

Update Credentials for an Endpoint.

Responds with either a CREDENTIAL_DAA or a CREDENTIAL_ECDSA object.

HTTP Request

POST https://xaptum.io/api/xiam/v1/endpoints/{ipv6_address}/credentials?{credential-type}

Path Parameters

Name Type Description
ipv6_address string ipv6_address

Query Parameters

Name Type Description
credential-type string daa or ecdsa

IAM Groups

GROUP Object

Attribute Type Description
gpk GROUP_PUBLIC_KEY
basename string variable-length byte array
networks [ipv6_network] *
default_network ipv6_network ?
onboarded_count number integer
provisioned_count number integer
creation_timestamp timestamp GMT, millisecond resolution
modification_timestamp timestamp GMT, millisecond resolution
gid GROUP_ID
domain ipv6_network
license LICENSE ?

NEW_GROUP Object

Example: provisionings

{
    "provisionings": [{
            "quantity": 10,
            "operator": "somebody",
            "group_id": "3EC837EC4D072E2189EF1F8B288475F02A11EE13722B9EC07A3F1C2E17A4B5D5"
    }],
    "group_public_key": "044072D214D22DADAA48CEBA0381A592337B587918049001AF6435C278BDC905D2AB840F41F4335D77B4970888B11C2C454B997AEEEF0641E1F6BDF8B8A17D5DBE397F8FED1F4FDCA94826FB1838200C2C45336FB4B346A8D06991F14B76714B27DA80BCD60B41B316D4B4C5A6925CE7951E2D995C30F9B4F059B6B454CBEDEA0104050A1B6C7CF4FF8A41BA9161CCD752512F54922E5D6551466260294D84B78F3117AAFAE2144B398B84CF5AF6520C1D9A4A52AA679E72E667E6E33A20E94B36885047C6D6CAB587E9AD37C73445BB7B031FA88C03E3C6DCAA8829DFF4A078EA1B1B2ADDC7905FB2C7C1FB2138025EF81C6BCC73B82BC19E5A746AD1B4DD3A06BD",
    "basename": "54455354424153454E414D45"
}

Example: minimal

{
    "group_public_key": "044072D214D22DADAA48CEBA0381A592337B587918049001AF6435C278BDC905D2AB840F41F4335D77B4970888B11C2C454B997AEEEF0641E1F6BDF8B8A17D5DBE397F8FED1F4FDCA94826FB1838200C2C45336FB4B346A8D06991F14B76714B27DA80BCD60B41B316D4B4C5A6925CE7951E2D995C30F9B4F059B6B454CBEDEA0104050A1B6C7CF4FF8A41BA9161CCD752512F54922E5D6551466260294D84B78F3117AAFAE2144B398B84CF5AF6520C1D9A4A52AA679E72E667E6E33A20E94B36885047C6D6CAB587E9AD37C73445BB7B031FA88C03E3C6DCAA8829DFF4A078EA1B1B2ADDC7905FB2C7C1FB2138025EF81C6BCC73B82BC19E5A746AD1B4DD3A06BD",
    "basename": "54455354424153454E414D45"
}

Example: default_network

{
    "group_public_key": "044072D214D22DADAA48CEBA0381A592337B587918049001AF6435C278BDC905D2AB840F41F4335D77B4970888B11C2C454B997AEEEF0641E1F6BDF8B8A17D5DBE397F8FED1F4FDCA94826FB1838200C2C45336FB4B346A8D06991F14B76714B27DA80BCD60B41B316D4B4C5A6925CE7951E2D995C30F9B4F059B6B454CBEDEA0104050A1B6C7CF4FF8A41BA9161CCD752512F54922E5D6551466260294D84B78F3117AAFAE2144B398B84CF5AF6520C1D9A4A52AA679E72E667E6E33A20E94B36885047C6D6CAB587E9AD37C73445BB7B031FA88C03E3C6DCAA8829DFF4A078EA1B1B2ADDC7905FB2C7C1FB2138025EF81C6BCC73B82BC19E5A746AD1B4DD3A06BD",
    "basename": "54455354424153454E414D45",
    "default_network": "2607:8F80:DEAD:BEEF::/64"
}
Attribute Type Description
group_public_key GROUP_PUBLIC_KEY
basename GROUP.basename
networks [ipv6_network]* GROUP.networks
provisionings [NEW_PROVISIONING] *
default_network ipv6_network ?
license NEW_LICENSE ?

MODIFIED_GROUP Object

Example: default_network

{
    "gid": "3EC837EC4D072E2189EF1F8B288475F02A11EE13722B9EC07A3F1C2E17A4B5D5",
    "default_network": "2607:8F80:DEAD:BEEF::/64"
}
Attribute Type Description
gid GROUP_ID
default_network ipv6_network ?
domain ipv6_network ?
license LICENSE ?

GROUP_PUBLIC_KEY Object

Attribute Type Description
type string enum IS(daa_lrsw_bn256
key string two x9.62-encoded Fp2 curve points

GROUP_ID Object

SHA256(GROUP.group_public_key | GROUP.basename)

Query Groups

Returns a list of Group Objects

HTTP Request

GET https://xaptum.io/api/xiam/v1/groups/?<query-string>

Query Parameters

Name Type Description
limit number integer
start string Encoded Group ID
network ipv6_network

Update Group

The request requires a New Group Object.

Returns a GROUP Object

HTTP Request

POST https://xaptum.io/api/xiam/v1/groups/?<query-string>

Query Parameters are the same as for the Query Groups

Get Group Detail

Returns a GROUP Object

HTTP Request

GET https://xaptum.io/api/xiam/v1/groups/{encoded-group-id}

Path Parameters

Name Type Description
encoded_group_id string GROUP_ID Object

Modify Group

The request requires a Modified Group Object

Returns a GROUP Object

HTTP Request

PUT https://xaptum.io/api/xiam/v1/groups/{encoded-group-id}

Path Parameters

Name Type Description
encoded_group_id string GROUP_ID Object

List a Group's Networks

Returns a list of NETWORK Objects

HTTP Request

GET https://xaptum.io/api/xiam/v1/groups/{encoded-group-id}/networks

Path Parameters

Name Type Description
encoded_group_id string GROUP_ID Object

Add Network to a Group

The request requires an IPv6 Address and returns the same.

HTTP Request

POST https://xaptum.io/api/xiam/v1/groups/{encoded-group-id}/networks

Path Parameters

Name Type Description
encoded_group_id string GROUP_ID Object

List a Group's Provisionings

Returns a list of PROVISIONING Objects

[
    {
        "quantity": 10,
        "operator": "somebody",
        "group_id": "3EC837EC4D072E2189EF1F8B288475F02A11EE13722B9EC07A3F1C2E17A4B5D5",
        "creation_timestamp": "2020-06-26T02:19:28.120Z"
    }
]

HTTP Request

GET https://xaptum.io/api/xiam/v1/groups/{encoded-group-id}/provisionings

Path Parameters

Name Type Description
encoded_group_id string GROUP_ID Object

PROVISIONING Object

The Provisioning object is used only for listing existing provisionings and creating a new one.

Attribute Type Description
group_id GROUP_ID
quantity number integer
operator string
creation_timestamp timestamp GMT, millisecond resolution

Add New Provisioning to Group

The request is a NEW_PROVISIONING Object

{
    "quantity": 10,
    "operator": "somebody",
    "group_id": "3EC837EC4D072E2189EF1F8B288475F02A11EE13722B9EC07A3F1C2E17A4B5D5"
}

Returns the PROVISIONING Object that was created.

{
    "quantity": 10,
    "operator": "somebody",
    "group_id": "3EC837EC4D072E2189EF1F8B288475F02A11EE13722B9EC07A3F1C2E17A4B5D5",
    "creation_timestamp": "2020-06-26T02:19:28.120Z"
}

HTTP Request

PUT https://xaptum.io/api/xiam/v1/groups/{encoded-group-id}/provisionings

NEW_PROVISIONING Object

The NEW_PROVISIONING Object is used only when adding a provisioning to a Group.

Attribute Type Description
group_id GROUP_ID
quantity number integer
operator string

IAM Networks

NETWORK Object

Attribute Type Description
address ipv6_network
groups [GROUP]*
endpoint_count number integer
endpoint_xtt_count number integer
endpoint_auth_count number integer
unassigned_count number integer
endpoint_limit number integer
creation_timestamp timestamp GMT, millisecond resolution
modification_timestamp timestamp GMT, millisecond resolution

List Networks

Returns a list of Network Objects

HTTP Request

GET https://xaptum.io/api/xiam/v1/networks

Add Networks

The request takes a NEW_NETWORK Object.

Request example: minimal

{
    "address": "2607:8F80:DEAD:BEEF::/64"
}

Request example: gids

{
    "gids": [
      "3EC837EC4D072E2189EF1F8B288475F02A11EE13722B9EC07A3F1C2E17A4B5D5"
    ],
    "address": "2607:8F80:DEAD:BEEF::/64"
}

Request example: endpoint_limit

{
    "endpoint_limit": 10,
    "address": "2607:8F80:DEAD:BEEF::/64"
}

Returns the Network Object that was just created.

HTTP Request

GET https://xaptum.io/api/xiam/v1/networks

NEW_NETWORK Object

Attribute Type Description
address ipv6_network
gids [GROUP_ID] *
endpoint_limit number ? integer

Get Network Detail

Returns a Network Object

The IPv6 address can be encoded either in CIDR format or in URL encoded format (surrounded with square brackets).

HTTP Request

GET https://xaptum.io/api/xiam/v1/networks/{cidr-ipv6-network-address}
GET https://xaptum.io/api/xiam/v1/networks/{urlencoded-cidr-ipv6-network-address}

Modify Network Detail

The request takes a Modified Network Object

Request example: modify endpoint_limit

{
    "endpoint_limit": 10
}

Returns a Network Object

The IPv6 address can be encoded either in CIDR format or in URL encoded format (surrounded with square brackets).

HTTP Request

PUT https://xaptum.io/api/xiam/v1/networks/{cidr-ipv6-network-address}
PUT https://xaptum.io/api/xiam/v1/networks/{urlencoded-cidr-ipv6-network-address}

MODIFIED_NETWORK Object

Attribute Type Description
endpoint_limit number ? integer

List a Network's Groups

Returns a list of Group Objects

List all of the groups associated with a Network.

The IPv6 address can be encoded either in CIDR format or in URL encoded format (surrounded with square brackets).

HTTP Request

GET https://xaptum.io/api/xiam/v1/networks/{cidr-ipv6-network-address}/groups
GET https://xaptum.io/api/xiam/v1/networks/{urlencoded-cidr-ipv6-network-address}/groups

Add a Group to a Network

The request takes a Group_ID Object.

The response returns the same Group_ID Object

HTTP Request

POST https://xaptum.io/api/xiam/v1/networks/{cidr-ipv6-network-address}/groups
POST https://xaptum.io/api/xiam/v1/networks/{urlencoded-cidr-ipv6-network-address}/groups

IAM Domains

DOMAIN Object

Attribute Type Description
address ipv6_network
default_license LICENSE
licenses LICENSE *
creation_timestamp timestamp GMT, millisecond resolution
modification_timestamp timestamp GMT, millisecond resolution

List Domains

Returns a list of Domain Objects

HTTP Request

GET https://xaptum.io/api/xiam/v1/domains

Create Domain

Request takes a New Domain object

{
    "default_license": {
      "endpoint_limit": 10
    }
}

Returns a Domain Object

HTTP Request

POST https://xaptum.io/api/xiam/v1/domains

NEW_DOMAIN Object

example

Attribute Type Description
address ipv6_network
default_license NEW_LICENSE

Get Domain of a Network

Returns a Domain Object

The IPv6 address can be encoded either in CIDR format or in URL encoded format (surrounded with square brackets).

HTTP Request

GET https://xaptum.io/api/xiam/v1/domains/{cidr-ipv6-network-address}
GET https://xaptum.io/api/xiam/v1/domains/{urlencoded-cidr-ipv6-network-address}

Modify Domain of a Network

Request takes a Modified Domain Object

Request example: endpoint_limit

{
    "default_license": {
      "endpoint_limit": 10
    }
}

Returns a Domain Object

The IPv6 address can be encoded either in CIDR format or in URL encoded format (surrounded with square brackets).

HTTP Request

PUT https://xaptum.io/api/xiam/v1/domains/{cidr-ipv6-network-address}
PUT https://xaptum.io/api/xiam/v1/domains/{urlencoded-cidr-ipv6-network-address}

MODIFIED_DOMAIN Object

Attribute Type Description
default_license NEW_LICENSE?

Firewall

(Brief description of firewall API)

(Base URL)

Overview

Errors

Pagination

Firewall Rule

Create a Firewall Rule

Delete a Firewall Rule

DNS

The ENF DNS is a managed, private Domain Name System service hosted within the ENF. You can use it to fully control DNS resolution for the endpoints on your ENF networks by creating private DNS zones, records, and servers.

Zone

An ENF zone is a collection of DNS records for a DNS domain (and possibly sub-domains). It is similar to a DNS zone), but is private and does not require domain registration. An network can be associated with multiple zones, allowing you to fully customize your DNS resolution.

Zone Object

Example Zone Object:

{
  "id": "b1afdfsa-932a-34ba-dfa32ss323adf",
  "zone_domain_name": "abc.def.xyz",
  "description": "A DNS domain.",
  "enf_domain": "fd00:8f80:8000::/48",
  "inserted_date": "2019-11-11T20:36:49Z",
  "modified_date": "2019-11-13T20:36:49Z"
}

The Zone Object represents an ENF zone.

Name Type Description
id string Unique identifier for the zone.
zone_domain_name string Name of the zone.
description string Description of the zone.
enf_domain ipv6_network The parent domain of the zone.
inserted_date timestamp The date that the zone was created.
modified_date timestamp The date that the zone was last modified. modified_date will be null if the zone has not been modified.

Create a Zone

enfcli-admin@acme> dns create-zone --zone-domain-name=abc.def.xyz --description="A DNS zone."
curl --request POST \
  --url https://xaptum.io/api/xdns/v1/zones \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"zone_domain_name":"abc.def.xyz","enf_domain":"fd00:8f80:8000::/48","description":"A DNS zone."}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

description = "A DNS zone"
zoneDomainName = "abc.def.xyz"

createZoneRequest := &CreateZoneRequest{
    Description: &description,
    ZoneDomainName: &zoneDomainName,
}

newEnfZone, resp, err := client.DNS.CreateZone(context.Background(), createZoneRequest)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"zone_domain_name\":\"abc.def.xyz\",\"enf_domain\":\"fd00:8f80:8000::/48\",\"description\":\"A DNS zone.\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"zone_domain_name\":\"abc.def.xyz\",\"enf_domain\":\"fd00:8f80:8000::/48\",\"description\":\"A DNS zone.\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xdns/v1/zones", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "id": "b1afdfsa-932a-34ba-dfa32ss323adf",
      "zone_domain_name": "abc.def.xyz",
      "description": "A DNS zone.",
      "enf_domain": "fd00:8f80:8000::/48",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint creates a new zone for a domain. Note that the zone_domain_name must be DNS-compliant.

HTTP Request

POST https://xaptum.io/api/xdns/v1/zones

Request Body

Name Type Description
zone_domain_name string The name of the new zone.
enf_domain string The domain to create the zone for.
description string The description of the new zone.

Get a List of Zones in a Domain

enfcli-admin@acme> dns list-zones
curl --request GET \
  --url 'https://xaptum.io/api/xdns/v1/zones' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

enfZones, resp, err := client.DNS.ListZones(context.Background())
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xdns/v1/zones", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "id": "b1afdfsa-932a-34ba-dfa32ss323adf",
      "zone_domain_name": "abc.def.xyz",
      "description": "A DNS zone.",
      "enf_domain": "fd00:8f80:8000::/48",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets a list of all the zones for a domain.

HTTP Request

GET https://xaptum.io/api/xdns/v1/zones

Get a Zone

enfcli-admin@acme> dns get-zone --zone-id=1fbbe711-2582-415e-a930-a6e561c06485
curl --request GET \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

zoneID := "1fbbe711-2582-415e-a930-a6e561c06485"

enfZone, resp, err := client.DNS.GetZone(context.Background(), zoneID)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "id": "b1afdfsa-932a-34ba-dfa32ss323adf",
      "zone_domain_name": "abc.def.xyz",
      "description": "A DNS zone.",
      "enf_domain": "fd00:8f80:8000::/48",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint gets the details of a zone.

HTTP Request

GET https://xaptum.io/api/xdns/v1/zones/{zone_id}

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

Update a Zone

enfcli-admin@acme> dns update-zone --zone-id=1fbbe711-2582-415e-a930-a6e561c06485 --description="Updated DNS zone."
curl --request PUT \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"description":"Updated DNS zone."}'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

newDescription := "Updated DNS zone."
updateZoneRequest := &UpdateZoneRequest{
  Description: &newDescription,
}

zoneID := "1fbbe711-2582-415e-a930-a6e561c06485"

updatedEnfZone, resp, err := client.DNS.UpdateZone(context.Background(), zoneID, updateZoneRequest)
if err != nil {
    // Handle error...
}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"description\":\"Updated DNS zone.\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485")
  .put(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"description\":\"Updated DNS zone.\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("PUT", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

{
  "data": [
    {
      "id": "b1afdfsa-932a-34ba-dfa32ss323adf",
      "zone_domain_name": "abc.def.xyz",
      "description": "Updated DNS zone.",
      "enf_domain": "fd00:8f80:8000::/48",
      "inserted_date": "2019-11-11T20:36:49Z",
      "modified_date": "2019-11-13T20:36:49Z"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint updates the description of a zone.

HTTP Request

PUT https://xaptum.io/api/xdns/v1/zones/{zone_id}

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

Request Body

Name Type Description
description string The new description for the zone.

Delete a Zone

enfcli-admin@acme> dns delete-zone --zone-id=1fbbe711-2582-415e-a930-a6e561c06485
curl --request DELETE \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
client := enf.NewClient("https://xaptum.io", nil)
// Authenticate the client here --- see the "Authentication" section above.

zoneID := "1fbbe711-2582-415e-a930-a6e561c06485"

resp, err := client.DNS.DeleteZone(context.Background(), zoneID)
if err != nil {
  // Handle error...
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485")
  .delete(null)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("DELETE", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns an HTTP response like this:

[]

This API endpoint deletes a zone.

HTTP Request

DELETE https://xaptum.io/api/xdns/v1/zones/{zone_id}

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

List the Networks in a Zone

enfcli-admin@acme> dns list-networks-in-zone --zone-id=1fbbe711-2582-415e-a930-a6e561c06485
curl --request GET \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

{
  "data": [
    {
      "created": "2019-12-26T18:23:55.141021Z",
      "enf_domain": "fd00:8f80:8000::/48",
      "enf_network": "fd00:8f80:8000:10::/64",
      "zone_id": "1fbbe711-2582-415e-a930-a6e561c06485"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint lists all the networks in a zone.

HTTP Request

GET https://xaptum.io/api/xdns/v1/zones/{zone_id}/networks

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

Add Networks to a Zone

enfcli-admin@acme> dns add-networks-to-zone --networks=fd00:8f80:8000:0000::/64, fd00:8f80:8000:1::/64 --zone-id=1fbbe711-2582-415e-a930-a6e561c06485
curl --request POST \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"networks":["fd00:8f80:8000:0000::/64","fd00:8f80:8000:1::/64"]}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"networks\":[\"fd00:8f80:8000:0000::/64\",\"fd00:8f80:8000:1::/64\"]}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"networks\":[\"fd00:8f80:8000:0000::/64\",\"fd00:8f80:8000:1::/64\"]}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

{
  "data": [
    {
      "created": "2019-12-26T18:23:55.141021Z",
      "enf_domain": "fd00:8f80:8000::/48",
      "enf_network": "fd00:8f80:8000:0000::/64",
      "zone_id": "1fbbe711-2582-415e-a930-a6e561c06485"
    },
    {
      "created": "2019-12-26T18:23:55.141021Z",
      "enf_domain": "fd00:8f80:8000::/48",
      "enf_network": "fd00:8f80:8000:1::/64",
      "zone_id": "1fbbe711-2582-415e-a930-a6e561c06485"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint adds a list of networks to a zone.

HTTP Request

POST https://xaptum.io/api/xdns/v1/zones/{zone_id}/networks

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

Request Body

Name Type Description
networks array(string) A list of network CIDRs to add to the zone.

Replace the Networks in a Zone

enfcli-admin@acme> dns replace-networks-in-zone --networks=fd00:8f80:8000:a::/64, fd00:8f80:8000:b::/64 --zone-id=1fbbe711-2582-415e-a930-a6e561c06485
curl --request PUT \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"networks":["fd00:8f80:8000:a::/64","fd00:8f80:8000:b::/64"]}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"networks\":[\"fd00:8f80:8000:a::/64\",\"fd00:8f80:8000:b::/64\"]}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks")
  .put(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"networks\":[\"fd00:8f80:8000:a::/64\",\"fd00:8f80:8000:b::/64\"]}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("PUT", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

{
  "data": [
    {
      "created": "2019-12-26T18:23:55.141021Z",
      "enf_domain": "fd00:8f80:8000::/48",
      "enf_network": "fd00:8f80:8000:a::/64",
      "zone_id": "1fbbe711-2582-415e-a930-a6e561c06485"
    },
    {
      "created": "2019-12-26T18:23:55.141021Z",
      "enf_domain": "fd00:8f80:8000::/48",
      "enf_network": "fd00:8f80:8000:b::/64",
      "zone_id": "1fbbe711-2582-415e-a930-a6e561c06485"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint lists all the networks in a zone.

HTTP Request

PUT https://xaptum.io/api/xdns/v1/zones/{zone_id}/networks

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

Request Body

Name Type Description
networks array(string) A list of network CIDRs that will replace the current list of networks for a zone.

Delete Networks from a Zone

enfcli-admin@acme> dns delete-networks-from-zone --network=fd00:8f80:8000:0000::/64 --zone-id=1fbbe711-2582-415e-a930-a6e561c06485
curl --request DELETE \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"networks":["fd00:8f80:8000:0000::/64"]}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"networks\":[\"fd00:8f80:8000:0000::/64\"]}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks")
  .delete(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"networks\":[\"fd00:8f80:8000:0000::/64\"]}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("DELETE", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/networks", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

[]

This API endpoint deletes a list of networks from a zone.

HTTP Request

DELETE https://xaptum.io/api/xdns/v1/zones/{zone_id}/networks

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

List Zones for a Network

enfcli-admin@acme> dns list-zones-in-network --network=fd00:8f80:8000:0000::/64
curl --request GET \
  --url https://xaptum.io/api/xdns/v1/networks/fd00:8f80:8000:0000::/64/zones \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/networks/fd00:8f80:8000:0000::/64/zones")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xdns/v1/networks/fd00:8f80:8000:0000::/64/zones", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

{
  "data": [
    {
      "id": "b1afdfsa-932a-34ba-dfa32ss323adf",
      "zone_domain_name": "abc.def.xyz",
      "description": "A DNS domain.",
      "enf_domain": "fd00:8f80:8000::/48",
      "created": "2019-11-11T20:36:49Z"
    }
  ],
  "page": {
    "curr": -1,
    "next": -1,
    "prev": -1
  }
}

This API endpoint lists all the zones the network is associated with.

HTTP Request

GET https://xaptum.io/api/xdns/v1/networks/{network}/zones

Path Parameters

Name Type Description
network string The /64 prefix of the network.

Server

A DNS server resolves DNS queries from endpoints on the network using the records in the network's associated zones. Each server is assigned an IPv6 address from the network's ::/64 prefix. Configure endpoints to use a server by adding that IPv6 to their DNS resolver configurations. Multiple servers may be provisioned within a network for redundancy or load-balancing.

Server Object

Example Server Object:

{
  "created": "2019-12-26T22:20:59.397715Z",
  "description": "This is a test",
  "enf_domain": "fd00:8f80:8000::/48",
  "enf_network": "fd00:8f80:8000:10::/64",
  "id": "4f063cfb-fff4-4ca3-8e3e-c9c022e5d49f",
  "ipv6": "fd00:8f80:8000:10::"
}

The Server Object represents an ENF DNS server.

Name Type Description
created timestamp Date and time that the service endpoint was created.
description string Description of the service endpoint.
enf_domain ipv6_network The parent domain of the service endpoiont.
enf_network ipv6_network The parent network of the service endpoint.
id string Unique identifier of the service endpoint.
ipv6 string IPv6 address of the service endpoint.

List the Servers in a Network

enfcli-admin@acme> dns list-servers --network=fd00:8f80:8000:0000::/64
curl --request GET \
  --url https://xaptum.io/api/xdns/v1/networks/fd00:8f80:8000::/64/servers \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/networks/fd00:8f80:8000::/64/servers")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xdns/v1/networks/fd00:8f80:8000::/64/servers", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

{
  "data": [
    {
      "created": "2019-12-26T22:20:59.397715Z",
      "description": "This is a test",
      "enf_domain": "fd00:8f80:8000::/48",
      "enf_network": "fd00:8f80:8000:10::/64",
      "id": "4f063cfb-fff4-4ca3-8e3e-c9c022e5d49f",
      "ipv6": "fd00:8f80:8000:10::"
    }
  ],
  "page": {
    "curr": "1",
    "next": "",
    "prev": ""
  }
}

This API endpoint lists all the servers in a network.

HTTP Request

GET https://xaptum.io/api/xdns/v1/networks/{network}/servers

Path Parameters

Name Type Description
network string The /64 prefix of the network.

Provision Servers in a Network

enfcli-admin@acme> dns provision-server --network=fd00:8f80:8000:0000::/64 --ipv6=fd00:8f80:8000:0000:10
curl --request POST \
  --url https://xaptum.io/api/xdns/v1/networks/fd00:8f80:8000:0000::/64
/servers \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"ipv6":"fd00:8f80:8000:0000:10","description":"DNS Service IPv6 address."}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"ipv6\":\"fd00:8f80:8000:0000:10\",\"description\":\"DNS Service IPv6 address.\"}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/networks/fd00:8f80:8000:0000::/64
/servers")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"ipv6\":\"fd00:8f80:8000:0000:10\",\"description\":\"DNS Service IPv6 address.\"}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xdns/v1/networks/fd00:8f80:8000:10::/64
/servers", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

{
  "data": [
    {
      "created": "2019-12-26T22:20:59.397715Z",
      "description": "This is a test",
      "enf_domain": "fd00:8f80:8000::/48",
      "enf_network": "fd00:8f80:8000:0000::/64",
      "id": "4f063cfb-fff4-4ca3-8e3e-c9c022e5d49f",
      "ipv6": "fd00:8f80:8000:10::"
    }
  ],
  "page": {
    "curr": "1",
    "next": "",
    "prev": ""
  }
}

This API endpoint provisions a server for a network. Note that the ipv6 and description parameters in the request body are optional; if the ipv6 parameter is not provided, the server will be automatically assigned an IPv6 address by the DNS.

HTTP Request

POST https://xaptum.io/api/xdns/v1/networks/{network}/servers

Path Parameters

Name Type Description
network string The /64 prefix of the network.

Request Body

Name Type Description
ipv6 string IPv6 address of the new service endpoint.
description string Description of the service endpoint.

Delete a Server

enfcli-admin@acme> dns delete-server --ipv6=fd00:8f80:8000:0000:10 --network=fd00:8f80:8000:0000::/64
curl --request DELETE \
  --url https://xaptum.io/api/xdns/v1/networks/fd00:8f80:8000:0000::/64/servers/fd00:8f80:8000:0000:10     \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/networks/fd00:8f80:8000:0000::/64/servers/fd00:8f80:8000:0000:10")
  .delete(null)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-45  60-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("DELETE", "/api/xdns/v1/networks/fd00:8f80:8000:0000::/64/servers/fd00:8f80:8000:0000:10", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

[]

This API endpoint deletes a serverfrom a network.

HTTP Request

DELETE https://xaptum.io/api/xdns/v1/networks/{network}/servers/{server_ip}

Path Parameters

Name Type Description
network ipv6_network The /64 prefix of the network.
server_ip string The IPv6 address of the server.

Record

An ENF record is simply a DNS record of type AAAA, TXT, SRV, or CNAME, and is associated with a zone.

Record Object

Example Record Object:

{
  "created": "2019-12-27T22:23:50.935312Z",
  "enf_domain": "fd00:8f80:8000::/48",
  "id": "042bde16-e060-498f-877c-075ce276c583",
  "name": "hvac-test-01.abc.def.xyz",
  "ttl": 300,
  "type": "AAAA",
  "value": {
    "ipv6": "fd00:8f80:8000:1:0:23cf:8e8c:0"
  },
  "zone_id": "1fbbe711-2582-415e-a930-a6e561c06485"
}

The Record Object represents a ENF DNS record.

Name Type Description
inserted_date timestamp Date and time that the record was created.
enf_domain ipv6_network Parent domain.
id string Unique identifier.
name string Full hostname.
ttl integer Time to live, in seconds.
zone_id string Unique identifier of the parent zone.
type string Type of the record. Four types are allowed in the ENF DNS: AAAA, TXT, SRV, and CNAME.
value object Relevant configuration values, dependent on the record type.

Record Value Object

Example Record Value Object:

{
  "ipv6": "fd00:8f80:8000:1:0:23cf:8e8c:0"
}

The Record Value Object represents the configuration values of a record. The structure of this object is dependent on its type.

Name Type Associated Record Type Description
ipv6 string AAAA IPv6 address to map the hostname to.
dname string CNAME Alias for the provided domain name.
priority integer SRV Priority of the target host.
weight integer SRV Relative weight for records with the same priority.
port integer SRV The TCP or UDP port on which the service is to be found.
target string SRV The hostname of the machine providing the service, ending in a dot.
txt string TXT Arbitrary text to associate with a hostname.

Query DNS for a Record

enfcli-admin@acme> dns query --name=hvac-test-01.abc.def.xyz --network=fd00:8f80:8000:0000::/64 --type=AAAA

This API endpoint queries the DNS for a record.

HTTP Request

GET https://xaptum.io/api/xdns/v1/networks/{network}/query/{type}/{name}

Path Parameters

Name Type Description
network string The /64 prefix of the network.
type string The type - either AAAA, TXT, SRV or CNAME - of the record.
name string The domain name of the record.

List Records in a Zone

enfcli-admin@acme> dns list-records --zone-id=1fbbe711-2582-415e-a930-a6e561c06485
curl --request GET \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/records \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/records")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = {
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("GET", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/records", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

{
  "data": [
    {
      "created": "2019-12-27T22:23:50.935312Z",
      "enf_domain": "fd00:8f80:8000::/48",
      "id": "042bde16-e060-498f-877c-075ce276c583",
      "name": "hvac-test-01.abc.def.xyz",
      "ttl": 300,
      "type": "AAAA",
      "value": {
        "ipv6": "fd00:8f80:8000:1:0:23cf:8e8c:0"
      },
      "zone_id": "1fbbe711-2582-415e-a930-a6e561c06485"
    }
  ],
  "page": {
    "curr": "1",
    "next": "",
    "prev": ""
  }
}

This API endpoint lists all the records in a zone.

HTTP Request

GET https://xaptum.io/api/xdns/v1/zones/{zone_id}/records

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

Create a Record in a Zone

enfcli-admin@acme> dns create-record --ttl=300 --type=AAAA --value=[fd00:8f80:8000:0000:0000] --zone-id=1fbbe711-2582-415e-a930-a6e561c06485
curl --request POST \
  --url https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/records \
  --header 'accept: application/json' \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652' \
  --header 'content-type: application/json' \
  --data '{"name":"hvac-01","type":"AAAA","ttl":300,"value":{"ipv6":"fd00:8f80:8000:0000:0000::"}}
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"name\":\"hvac-01\",\"type\":\"AAAA\",\"ttl\":300,\"value\":{\"ipv6\"}}");
Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/records")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

payload = "{\"name\":\"hvac-01\",\"type\":\"AAAA\",\"ttl\":300,\"value\":{\"ipv6\":\"fd00:8f80:8000:0000:0000::\"}}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652"
    }

conn.request("POST", "/api/xdns/v1/zones/1fbbe711-2582-415e-a930-a6e561c06485/records", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

This API endpoint creates a record in a zone.

HTTP Request

POST https://xaptum.io/api/xdns/v1/zones/{zone_id}/records

Path Parameters

Name Type Description
zone_id string The unique identifier of the zone.

Get a Record in a Zone

enfcli-admin@acme> dns delete-record --id=f75b78c8-c7fe-429a-9960-96af3a67ddbc
curl --request GET \
  --url https://xaptum.io/api/xdns/v1/records/f75b78c8-c7fe-429a-9960-96af3a67ddbc \
  --header 'authorization: Bearer f648eea2-3704-4560-bb46-bfff79712652'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://xaptum.io/api/xdns/v1/records/f75b78c8-c7fe-429a-9960-96af3a67ddbc")
  .get()
  .addHeader("authorization", "Bearer f648eea2-3704-4560-bb46-bfff79712652")
  .build();

Response response = client.newCall(request).execute();
import http.client

conn = http.client.HTTPSConnection("xaptum.io")

headers = { 'authorization': "Bearer f648eea2-3704-4560-bb46-bfff79712652" }

conn.request("GET", "/api/xdns/v1/records/f75b78c8-c7fe-429a-9960-96af3a67ddbc", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The above command returns the an HTTP response like this:

[]

This API endpoint deletes a record in a zone.

HTTP Request

DELETE https://xaptum.io/api/xdns/v1/records/{record_id}

Path Parameters

Name Type Description
record_id string The unique identifier of the record.

Router Cards

The captive API allows control of the captive router card. The API allows control of device configurations including wifi and firmware updates. It also retrieves status of devices.

Data Types & Structures

The router card API uses several JSON objects in queries and responses.
Individual fields may be included / excluded depending on where the object is used.
The New/Update columns indicate that the field is required on creation/update of the resource using the object.

The JSON objects are defined below, with the REST resources that use them.

Legend

The inclusion of fields in the object is defined as listed below.
✓ - indicates that the field is mandatory.
? - inicates that the field is optional.

Columns

New : The checked fields must be included when creating a new object

Full : The checked fields are included when the resource returns the full object. This is the default. Unless otherwise indicated, child object will display fields indicated by the summary column.

Summary : The checked fields are included when the resource returns a summary object. Child objects will return only the ID fields unless otherwise specified. Summary views are normally used when a list of objects is requested.

ID : When the parent object field specifies ID, only this field will be returned in the object. This will always be the ID field of the object. This is used when creating or updating an object.

Update : Indicates which fields to include in the PUT request to update the object.

For new object creation, such as a POST request, if a top-level object (parent) includes one or more child objects, both the parent and child objects must include the fields specified in the New column, listed below.
See the wifi POST for an example.

For a response that is listed as Full from a request such as POST or GET, the parent object will contain the fields from the Full columns and the child objects will contain the Summary fields.
See the response from the Create WIFI Configuration for an example.

In both cases, the child object fields should be listed after the parent object fields.

For a response that is listed as Summary from a request, the object will contain all of the fields from the Summary columns and will not contain any child object.

For Example: If the resource returns the summary version of the PROFILE object, the PROFILE object will not include any WIFI objects.

Not all columns are applicable to all objects.

Symbols:

: This field is required

? : This field is optional

WIFI

WIFI Objects

These objects are used in sending requests to and getting responses from the WIFI REST resources.

WIFI

Example of a full WIFI object:

{
    "id": "5f366cf1-c891-4737-b3fe-c27487fd9825",
    "name": "wifi-simple-static",
    "domain": null,
    "description": "new wifi structure with a single, static network",
    "version": 3,
    "operator": "JohnQ@public.com",
    "networks": [
        {
            "name": "static_net_psk",
            "SSID": "secure-host",
            "SSID_type": "string",
            "auth": {
                "type": "psk",
                "passphrase": "secure-host-passphrase"
            },
            "IPv4": {
                "type": "static",
                "address": "192.168.1.101",
                "mask": "255.255.255.0",
                "gateway": "192.168.1.1"
            },
            "IPv6": {
                "type": "auto"
            }
        }
    ],
    "passthrough_sha256": "37162baef24e3c622057288db035f8723924d859e0e339403c072cf910c78f37",
    "secure_sha256": "07432a3c0a0c651f7fa8f88ae2dd427566da230f1605c0809e045d398143156f"
}
Field Type Full Summary New Update
id uuid
name string ?
domain * ipv6_network
description string ? ? ? ?
version int
operator string
networks [WIFI.NETWORK] ?
passthrough_sh256 string
secure_sha256 string

* Only accessible to Xaptum administrators

WIFI.NETWORK

Sample WIFI.NETWORK object. This is usually part of another object such as a WIFI object.

{
    "IPv4": {
        "type": "dhcp"
    },
    "IPv6": {
        "type": "auto"
    },
    "SSID": "somethingOrOther",
    "SSID_type": "string",
    "auth": {
        "passphrase": "NotValid123",
        "type": "psk"
    },
    "name": "nonExistent"
}
Field Type Full Summary New Update
name string
SSID string
SSID_type "string" \ "hex"
(defaults to "string")
?
auth WIFI.NETWORK.PSK ? ? ?
ipv4 WIFI.NETWORK.IPV4_OFF
| WIFI.NETWORK.IPV4_DHCP
| WIFI.NETWORK.IPV4_STATIC
? ? ?
ipv6 WIFI.NETWORK.IPV6_OFF
| WIFI.NETWORK.IPV6_AUTO
| WIFI.NETWORK.IPV6_STATIC
? ? ?

WIFI.NETWORK items are never actually updated, they are replaced in their entirety. To update an existing object, specify a new one with the same sequence number.

WIFI.NETWORK.PSK

Field Type Full New Update
type "psk"
passphrase string

List WIFI configurations

Example of a response that returns a list of two WIFI objects in summary form.

[
    {
        "id" : "6a993284-fe1f-4fa1-a78f-db51613d79cd",
        "name" : "chicago-north",
        "version" : 2
    },
    {
        "id" : "e46b3356-fe85-4836-a65a-333fb473e871",
        "name" : "cleveland",
        "version" : 1
    }
]

Returns the summary information of the latest version of each wifi profile.

HTTP Request

GET https://xaptum.io/api/captive/v1/wifi

Create WIFI configuration

Example JSON data that would be submitted with a POST when creating a new wifi profile. This example would also work for updating a wifi profile via a PUT request.

{
    "name" : "chi-north-floor2",
    "networks" : [
        {
            "name" : "chicago-north-secure",
            "SSID" : "ORD-N-secure",
            "auth" : {
                "type" : "psk",
                "passphrase" : "Password123"
            },
            "ipv6" : {
                "type" : "auto"
            }
        },
        {
            "name" : "XFINITY",
            "SSID" : "XFINITY",
            "auth" : {
                "type" : "psk",
                "passphrase" : "Random4567"
            },
            "ipv4" : {
                "type" : "dhcp"
            }
        }
    ]
}

Response is full detail of the WIFI object created.

{
    "id" : "6a993284-fe1f-4fa1-a78f-db51613d79cd",
    "name" : "chi-north-floor2",
    "domain": null,
    "version": 5,
    "operator": "JaneDoe@someemail.com",
    "networks" : [
        {
            "name" : "chicago-north-secure",
            "SSID" : "ORD-N-secure",
            "SSID_type": "string",
            "auth" : {
                "type" : "psk",
                "passphrase" : "Password123"
            },
            "ipv6" : {
                "type" : "auto"
            }
        },
        {
            "name" : "XFINITY",
            "SSID" : "XFINITY",
            "SSID_type": "string",
            "auth" : {
                "type" : "psk",
                "passphrase" : "Random4567"
            },
            "ipv4" : {
                "type" : "dhcp"
            }
        }
    ]
}

Creates a new wifi profile.

HTTP Request

POST https://xaptum.io/api/captive/v1/wifi

Query WIFI configuration

The response to a WIFI query is the same format as for the List Wifi Configurations.

Returns the details of the latest version of each configuration matching the query.

HTTP Request

GET https://xaptum.io/api/captive/v1/wifi?{wifi_query}

Query Parameters

Name Type Description
wifi_query string String to match wifi configurations

Get WIFI configuration detail

The response to a GET of a specific WIFI Configuration is the same format as the response to a Create WIFI Configuration

Returns wifi configuration uniquely specified by the UUID
The second form returns a specific version of the wifi configuration.

HTTP Request

GET https://xaptum.io/api/captive/v1/wifi/{WIFI.id}

GET https://xaptum.io/api/captive/v1/wifi/{WIFI.id}?version={version}

Path Parameters

Name Type Description
WIFI.id UUID UUID of WIFI configuration to retrieve.
version integer Version to be returned

Update WIFI configuration

{% include wifi-object-full.md %}

Example JSON data sent with the update PUT request. This example only updates the name of the WIFI configuration.

{
    "name" : "chi-north-floor4"
}

The response is the full detail of the WIFI object, similar to the response to the Create WIFI Configuration

{
    "id" : "6a993284-fe1f-4fa1-a78f-db51613d79cd",
    "name" : "chi-north-floor4",
    "domain": null,
    "version": 5,
    "operator": "JaneDoe@someemail.com",
    "networks" : [
        {
            "name" : "chicago-north-secure",
            "SSID" : "ORD-N-secure",
            "SSID_type": "string",
            "auth" : {
                "type" : "psk",
                "passphrase" : "Password123"
            },
            "ipv6" : {
                "type" : "auto"
            }
        },
        {
            "name" : "XFINITY",
            "SSID" : "XFINITY",
            "SSID_type": "string",
            "auth" : {
                "type" : "psk",
                "passphrase" : "Random4567"
            },
            "ipv4" : {
                "type" : "dhcp"
            }
        }
    ]
}

The server will create a new version of the wifi config record and schedule an update for all of the devices that are using the matching configuration.

HTTP Request

PUT https://xaptum.io/api/captive/v1/wifi/{WIFI.id}

Path Parameters

Name Type Description
WIFI.id UUID UUID of WIFI configuration to update.

Profiles

Profile Objects

The following objects are use in creating, updating, and querying the Profile REST resources.

PROFILE

Sample PROFILE object

{
    "id": "32e4e14f-2bfd-49e8-98d8-d752ca4411c3",
    "name": "test0830",
    "domain": null,
    "config": {
        "version": 1,
        "mode": "secure-host",
        "wifi": {
            "domain": "2607:8f80:8100::/48",
            "id": "6fcbafb0-350c-46a4-87ee-dffa0309ba08",
            "name": "wifi-simple-static",
            "version": 3
        },
        "operator": "JaneDoe@someemail.com",
        "firmware": null
    }
}
Field Type Full Summary ID New Update
id uuid
name string ?
domain * [ipv6_network]
config object ?
config.version int
config.mode DEVICE.MODE ?
config.wifi WIFI (summary) ID ? ID ? ID ?
config.operator string
config.firmware FIRMWARE_UPDATE (summary) ID ? ID ? ID ?

The config.version is created and automatically incremented by the server. This field can not be edited by the user.

List captive device profiles

Example JSON list of PROFILE objects in summary form.

[
    {
        "config": {
            "firmware": null,
            "mode": "secure-host",
            "version": 1,
            "wifi": {
                "id": "6fcbafb0-350c-46a4-87ee-dffa0309ba08"
            }
        },
        "domain": "2607:8f80:8100::/48",
        "id": "c65b0f00-fe79-498e-bcb6-6686128a6fd6",
        "name": "secure1"
    },
    {
        "config": {
            "firmware": null,
            "mode": "secure-host",
            "version": 1,
            "wifi": {
                "id": "e79d109a-f72f-4704-984b-2ca7d2aa653f"
            }
        },
        "domain": "2607:8f80:8100::/48",
        "id": "2e3fc37b-db83-429b-9106-92cb468a2d70",
        "name": "make_secure"
    },
    {
        "config": {
            "firmware": null,
            "mode": "secure-host",
            "version": 1,
            "wifi": {
                "id": null
            }
        },
        "domain": null,
        "id": "270cd45e-cf1f-4570-b4bb-9b0baa4a915b",
        "name": "defaut"
    }]

Returns a list of all of the existing device profiles. The PROFILE objects will be in summary form.

HTTP Request

GET https://xaptum.io/api/captive/v1/profile

Create new profile

Example JSON data to submit with creation POST message

{
    "name" : "Boise Network",
    "config" : {
        "mode" : "secure-host",
        "wifi" : {
            "id" : "914b8eee-6de7-4108-8cf7-6dd62bc9790a"
        }
    }
}

A detailed profile object is returned in response to a POST that creates a new profile.

{
    "id" : "e2506422-7710-4024-a0a6-cf83d4f7c7c5",
    "name" : "Boise Network",
    "domain": null,
    "config" : {
        "version" : 1,
        "mode" : "secure-host",
        "wifi" : {
            "id" : "914b8eee-6de7-4108-8cf7-6dd62bc9790a",
            "domain" : "fd00:8f80:8000::9a79:dead:beef/48",
            "name" : "boise-net",
            "version" : 1
        },
        "operator": "JaneDoe@someemail.com",
        "firmware": null
    }
}

The server will create a new profile from the data in the request. The server will return a list containing only the newly created profile. The profile may contain WIFI.id if the desired profile already exists.

HTTP Request

POST https://xaptum.io/api/captive/v1/profile

Query captive-device profiles

The response to a profile query is the same format as for the List Profiles command.

Returns a list of all of the device profiles that match the query.

HTTP Request

GET https://xaptum.io/api/captive/v1/profile?{profile_query}

Query Parameters

Name Type Description
profile_query string String to match profiles.

Get captive-profile detail

The response is the full detail of the profile object. This is the same format as the response to the Create New Profile

Returns the profile indicated by the PROFILE.id (uuid).
The second form returns the specified version of the profile.

HTTP Request

GET https://xaptum.io/api/captive/v1/profile/{PROFILE.id}

GET https://xaptum.io/api/captive/v1/profile/{PROFILE.id}?version={version}

Path Parameters

Name Type Description
PROFILE.id UUID UUID of profile to retrieve.
version integer Version to be returned

Update Profile

An example of JSON data to submit with an update PUT message This example modifies the name, mode, and wifi configuration.

{
    "name" : "OLD Chicago Network",
    "config" : {
        "mode" : "secure-host",
        "wifi" : {
            "id" : "70698ae1-b841-48e4-86d4-c478fc193f68"
        }
    }
}

The response is the full detail of the PROFILE object.

The server will update the device profile and schedule an update for all of the devices that are using the matching configuration.

HTTP Request

PUT https://xaptum.io/api/captive/v1/profile/{PROFILE.id}

Path Parameters

Name Type Description
PROFILE.id UUID UUID of profile to update.

Get WIFI configuration used by a profile

The response is the full detail of the WIFI object, similar to the response to the Create WIFI Configuration

Returns the wifi configuration used by the device profile indicated by the PROFILE.id (uuid).

HTTP Request

GET https://xaptum.io/api/captive/v1/profile/{PROFILE.id}/wifi

Path Parameters

Name Type Description
PROFILE.id UUID UUID of profile to update.

Update WIFI configuration used by a captive-profile

Example JSON to submit with a PUT request that takes a WIFI.id

{
    "6a993284-fe1f-4fa1-a78f-db51613d79cd"
}

The response is the full detail of the WIFI object, similar to the response to the Create WIFI Configuration

The server will update the profile to use a different WIFI configuration.
The WIFI configuration must already exist.
The server will schedule an update for all of the devices that are using device profile indicated by the PROFILE.id (uuid).

HTTP Request

PUT https://xaptum.io/api/captive/v1/profile/{PROFILE.id}/wifi

Path Parameters

Name Type Description
PROFILE.id UUID UUID of profile to update.

Get captive-profile mode

Querying the mode of a profile returns JSON containing only the mode.

{ "secure-host" }

Returns the mode for the device-profile indicated by PROFILE.id.

HTTP Request

GET https://xaptum.io/api/captive/v1/profile/{PROFILE.id}/mode

Path Parameters

Name Type Description
PROFILE.id UUID UUID of profile to update.

Update captive-profile mode

The format for the request and the response are identical.

{ "secure-host" }

The server will update device mode and schedule an update for all of the devices that are using device-profile indicated by PROFILE.id.
NOTE: Currently, only secure-host mode is supported.

HTTP Request

PUT https://xaptum.io/api/captive/v1/profile/{PROFILE.id}/mode

Path Parameters

Name Type Description
PROFILE.id UUID UUID of profile to update.

Device

Device Objects

These objects are used in sending requests and the replies from the Device REST resources.

DEVICE

Example DEVICE object

{
    "control_address": "2607:8F80:8100:0:E78D:C0C0:20CF:92DC",
    "device_address": "2607:8F80:8080:9:D5AF:96FC:749C:D44C",
    "device_name": "xdemo-03",
    "firmware_version": "1.2.0",
    "mac_address": {
        "1": "B0:A6:F5:00:0F:BE",
        "2": "B0:A6:F5:00:0F:BF",
        "3": "B0:A6:F5:00:0F:C0",
        "4": "B0:A6:F5:00:0F:C1"
    },
    "model": "xaprw001_dev",
    "profile": {
        "config": {
            "version": 32
        },
        "id": "cd74a954-227f-4749-b6e6-fa8bf99d9b45",
        "name": "make_or_xaptum_test"
    },
    "serial_number": "XRW04419003112",
    "status": {
        "firmware": {
            "image_name": null,
            "state": "normal"
        },
        "mode": "secure-host",
        "serial_number": "XRW04419003112",
        "wifi": {
            "SSID": "MakeOffices",
            "connected": true
        }
    }
}
Field Type Full Summary ID New Update
serial_number string
device_name string ? ?
control_address * ipv6_address
(nullable)
device_address ipv6_address
(nullable)
mac_address MACADDRESS
firmware_version string
(nullable)
model string ?
profile PROFILE
(nullable)
(Summary) ID ? ID ?
changes_pending bool V2+ V2+
status DEVICE.STATUS
(nullable)
(Summary) (Summary)

* Only accessible to Xaptum administrators

DEVICE.MODE

DEVICE.MODE : "passthrough" | "secure-host" | "secure-lan"

DEVICE.STATUS

This entire object may be null if the server has not yet been able to contact the device.

Field Type Full Summary
serial_number string
mode DEVICE.MODE
uptime number (seconds since boot)
refresh_time timestamp (ISO 8601 format)
wifi object
wifi.connected bool
wifi.SSID string
wifi.IPv4_addresses [ipv4_address]
wifi.IPv6_addresses [ipv6_address]
wifi.config WIFI (Summary)
firmware FIRMWARE_STATUS

The configuration returned in the DEVICE.STATUS object shows what is currently running on the card. This might be different than what was configured in the profile if the changes have not yet propogated.

MACADDRESS

Field Type Full Summary
1 string
2 * string
3 * string
4 * string

* Only accessible to Xaptum administrators

List devices

Example of a JSON response that contains a list of DEVICE objects. Since it is a list, only summary information will be included.

[
    {
        "serial_number" : "axf412",
        "device_name" : null,
        "device_address" : "fd00:8f80:8000::9a79:dead:beef",
        "model": "xaprw001",
        "status" : {
            "serial_number" : "axf412",
            "mode" : "secure-host",
            "wifi" : {
                "connected" : true,
                "SSID" : "mcdonalds free wifi"
            }    
        }
    },
    {
        "serial_number" : "axf413",
        "device_name" : "",
        "device_address" : "fd00:8f80:8000::9a79:dead:bebe",
        "model": "xaprw001",
        "status" : {
            "serial_number" : "axf413",
            "mode" : "secure-host",
            "wifi" : {
                "connected" : true,
                "SSID" : "starbucks"
            }    
        }
    }
]

Returns the basic status and configuration information of each device. Only the currently running version is returned -- if there are unapplied changes, they will not be shown.

HTTP Request

GET https://xaptum.io/api/captive/v1/device

Create Device

Example of the JSON data that Xaptum administrators provide to create a DEVICE object.

{
    "serial_number" : "axf412",
    "mac_address" : {
        "1" : "f0:18:98:47:0f:20",
        "2" : "f0:18:98:47:0f:21",
        "3" : "f0:18:98:47:0f:22",
        "4" : "f0:18:98:47:0f:23"
    }
}

The response to a device creation will be a full DEVICE Object

Creates a device object and returns the created device. Creation is only available to Xaptum Administrators.

HTTP Request

POST https://xaptum.io/api/captive/v1/device

Query Devices

The response to a device query returns a list in the same format as the response for the List Devices

Returns all device status and configuration information for devices that match the query.

HTTP Request

GET https://xaptum.io/api/captive/v1/device?{device_query}

Query Parameters

Name Type Description
device_query string String to match devices.

Get Device Detail

The response to a Device Detail request will be a full DEVICE Object

Returns the configuration and status of the device with the specified DEVICE.ID.

HTTP Request

GET https://xaptum.io/api/captive/v1/device/{DEVICE.ID}

Path Parameters

Name Type Description
DEVICE.id DEVICE.ID serial number, device address, or control address

Update or Create Device

Not implemented yet.

HTTP Request

PUT https://xaptum.io/api/captive/v1/device/{DEVICE.ID}

Get Device Status

DEVICE.STATUS object

{
    "serial_number" : "axf412",
    "mode" : "secure-host",
    "uptime" : 123412,
    "status_refresh_time" : "2019-04-17T14:46:18-06:00",
    "wifi" : {
        "connected" : true,
        "SSID" : "mcdonalds free wifi",
        "IPv4_addresses" : [
            "192.168.1.413"
        ],
        "IPv6_addresses" : [
            "fd00:8f80:8000::9a79:dead:beef",
            "fd00:8f80:8000::9a79:0123:abcd"
        ],
        "config" : {
            "id" : "28946878-6e08-4838-a870-c40244169746",
            "name" : "Chicago Network",
            "version" : 7
        }
    }
}

Returns the status of the device with the specified DEVICE.ID.
This will return what is currently running on the device. The status may not match the configuration if the changes have not been applied.

HTTP Request

GET https://xaptum.io/api/captive/v1/device/{DEVICE.ID}/status

Path Parameters

Name Type Description
DEVICE.id DEVICE.ID serial number, device address, or control address

Get Device Mode

The device mode, by itself, will be returned as a JSON string.

{ "secure-host" }

Returns a json string containing the mode that the device is currently running. This may be different than what is configured if the change has not been applied.

HTTP Request

GET https://xaptum.io/api/captive/v1/device/{DEVICE.ID}/status/mode

Get Device's WIFI status

The response to a GET of a specific device WIFI Configuration is the same format as the response to a Create WIFI > Configuration

Returns wifi profile that is currently running on the device. This may be different than what is configured if the change has not been applied.

HTTP Request

GET https://xaptum.io/api/captive/v1/device/{DEVICE.ID}/status/wifi

Get Device's Firmware status

The response to the firmware status request.

{
  "running_version": "1.2.0-0",
  "running_image": "xaprw001_dev-v1.2.0-0-g25a335e",
  "update_state": "normal"
}

Returns the update state and the version of the firmware that is currently running on the device. This may be different than what is configured if the change has not been applied.

HTTP Request

GET https://xaptum.io/api/captive/v1/device/{DEVICE.ID}/status/firmware

Get Device's configured profile

The response is the full detail of the profile object. This is the same format as the response to the Create New Profile

Returns the configured profile of the device with the specified DEVICE.ID. This might be different than what is running if updates have not propagated.

HTTP Request

GET https://xaptum.io/api/captive/v1/device/{DEVICE.ID}/profile

Change device's configured profile

The PUT request must be accompanied by the profile ID of the new profile.

{ "28946878-6e08-4838-a870-c40244169746" }

The response is the full detail of the profile object. This is the same format as the response to the Create New Profile

The server will set the specified device’s profile to be the one indicated by the PROFILE.id. The profile must already exist.

HTTP Request

PUT https://xaptum.io/api/captive/v1/device/{DEVICE.ID}/profile

Get Device's configured WIFI settings

The response is the full detail of the WIFI object, similar to the response to the Create WIFI Configuration

Returns the configured wifi profile of the device with the specified DEVICE.ID. This might be different than what is running if updates have not propagated.

HTTP Request

GET https://xaptum.io/api/captive/v1/device/{DEVICE.ID}/wifi

Get Device's configured mode

The mode returns a single JSON string with the configured mode.

{ "secure-host" }

Returns a string containing the mode that is configured for the specified device. This may be different than what is currently running if the change has not been applied.

HTTP Request

GET https://xaptum.io/api/captive/v1/device/{DEVICE.ID}/mode

Query devices for status

The response will be a list of a list of DEVICE.STATUS objects.

[
    {
        "serial_number" : "axf412",
        "mode" : "secure-host",
        "wifi" : 
         {
             "connected" : true,
             "SSID" : "mcdonalds free wifi"
         }

    },
    {
        "serial_number" : "afx413",
        "mode" : "secure-host",
        "wifi" : 
        {
            "connected" : true,
            "SSID" : "mcdonalds free wifi"
        }   
    }
]

Description

HTTP Request

GET https://xaptum.io/api/captive/v1/device/status?{device_query}

Query Parameters

Name Type Description
device_query string String to match devices.

Firmware

List available image versions

The command returns an HTTP response like this:

{"Needs example"}

Permitted roles: DOMAIN_ADMIN and above

Lists available image versions RELEASE.Summary

HTTP Request

GET https://xaptum.io/api/captive/v1/firmware/release

Get detail on image version

The command returns an HTTP response like this:


{"Needs example"}

Permitted roles: DOMAIN_ADMIN and above

Returns details of all of the files that were built for the specified version.

HTTP Request

GET https://xaptum.io/api/captive/v1/firmware/release/{version}

Path Parameters

Name Type Description
version string The version number in which we're interested

List Firmware Updates

Returns a list of FIRMWARE_UPDATE objects.

{"Needs example - list of firmware updates"}

Lists available FIRMWARE_UPDATE objects.

HTTP Request

GET https://xaptum.io/api/captive/v1/firmware/update

Create Firmware Update

The request and the response formats are both FIRMWARE_UPDATE objects.

{"Needs example - Firmware update detail"}

Creates a new FIRMWARE_UPDATE object.

HTTP Request

POST https://xaptum.io/api/captive/v1/firmware/update

Get firmware update detail

Returns a detailed FIRMWARE_UPDATE object in the same format as the response to Create Firmware Update

Retrieves details on the specific FIRMWARE_UPDATE object

HTTP Request

GET https://xaptum.io/api/captive/v1/firmware/update/{FIRMWARE_UPDATE.id}

Path Parameters

Name Type Description
FIRMWARE_UPDATE.id string UUID of the firmware udpate object

Modify firmware update object

The request will send a JSON with the fields that are to be updated.

Needs example

Returns a detailed FIRMWARE_UPDATE object in the same format as the response to Create Firmware Update

Updates an existing FIRMWARE_UPDATE object.

HTTP Request

PUT https://xaptum.io/api/captive/v1/firmware/update/{FIRMWARE_UPDATE.id}

Schedule

List Update Schedules

Returns a list of schedule objects.

Needs example

Permitted roles: DOMAIN_ADMIN and above

Lists available schedules SCHEDULE

HTTP Request

GET https://xaptum.io/api/captive/v1/schedule

Create Update Schedule

Both the request and the response are schedule objects.

Needs example

Permitted roles: DOMAIN_ADMIN and above

Creates new schedule object SCHEDULE

HTTP Request

POST https://xaptum.io/api/captive/v1/schedule

Get Schedule detail

Returns a full schedule object in the same format as the response to Create Update Schedule

Permitted roles: DOMAIN_ADMIN and above

Gets details for specific SCHEDULE

HTTP Request

GET https://xaptum.io/api/captive/v1/schedule/{schedule-id}

Path Parameters

Name Type Description
schedule-id string The UUID of the schedule.

Modify Update Schedule

The request data is a SCHEDULE object containing only the fields that are changing.

Needs example

The response is the same format as the response to Create Update Schedule

Permitted roles: DOMAIN_ADMIN and above

Updates an existing schedule object

HTTP Request

PUT https://xaptum.io/api/captive/v1/schedule/{schedule-id}

Delete Schedule

Response
200 OK - on successful deletion of
409 - if is being used by pending updates.

Permitted roles: DOMAIN_ADMIN and above

Deletes the specified schedule object. Can not be deleted if updates are pending.

HTTP Request

GET https://xaptum.io/api/captive/v1/schedule