Portal Privision Intergration – Preview

🛡️ Guardian API – Early Access Integration Guide #

This document outlines the early-stage Guardian API endpoints for developers looking to automate portal and domain provisioning on VeilNet.

⚠️ Note: Guardian API integration is still under development. Currently, only admin accounts can authenticate via /auth/login. Programmatic access for regular users will be rolled out in future updates.

1️⃣ Obtain Access Token #

Use your admin credentials to get an access token via:

				
					curl -X GET https://guardian.veilnet.org/auth/token \
  -H "Authorization: Bearer <admin_login_token>"

2️⃣ List Available Domains #

Public Domains

				
					curl -X GET https://guardian.veilnet.org/domain/public/list \
  -H "Authorization: Bearer <access_token>"

Private Domains

				
					curl -X GET https://guardian.veilnet.org/domain/private/list \
  -H "Authorization: Bearer <access_token>"

3️⃣ Create a Portal #

You can create a public or private portal by sending a POST request with the following query parameters:

🔧 Required Query Parameters #

portal_name – the name of the portal.
Must be unique per user per region.
domain_name – the name of the domain the portal will join.
Must match an existing public or private domain.
region – the region where the portal will operate (e.g., uk, us, sg).
Must match the domain’s region.

🏷️ Optional Query Parameter #

tag – an optional label for internal grouping or description (e.g., prod, office, vps1)

🌀 Example: Create Public Portal

				
					curl -X POST "https://guardian.veilnet.org/portal/public?portal_name=myportal&domain_name=my-public-domain&region=uk&tag=edge" \
  -H "Authorization: Bearer <access_token>"

🔐 Example: Create Private Portal

				
					curl -X POST "https://guardian.veilnet.org/portal/private?portal_name=homebox&domain_name=corp-domain&region=uk" \
  -H "Authorization: Bearer <access_token>"

✅ Response #

Returns:

cert_pem, key_pem, ca_pem – for secure mutual TLS
network and domain info – for auto configuration
unique portal_id – used for further actions like local network attachment

You need the response to configure and launch your portal container. With valid auth token, portal name, domain name and region, the portal container will pull its configuration automatically.

4️⃣ Launch the Portal #

Once your portal is created and credentials are ready, you can launch the portal directly using Docker:

				
					docker run -d \
  --name veilnet-portal \
  --restart unless-stopped \
  --privileged \
  -e VEILNET_GUARDIAN_URL=https://guardian.veilnet.org \
  -e VEILNET_ANCHOR_TOKEN=<your_anchor_token> \
  -e VEILNET_ANCHOR_NAME=<your_portal_name> \
  -e VEILNET_DOMAIN_NAME=<your_domain_name> \
  -e VEILNET_REGION=<region> \
  -e PUBLIC=true \
  ulfaric/veilnet-portal:1.0.0

📌 Required Environment Variables #

VEILNET_GUARDIAN_URL – URL to the Guardian API
VEILNET_ANCHOR_TOKEN – your portal’s token from API response
VEILNET_ANCHOR_NAME – portal name (must match what you used to create it)
VEILNET_DOMAIN_NAME – the domain this portal joins
VEILNET_REGION – must match the domain’s region exactly
PUBLIC – true or false depending on domain type

✅ The portal will automatically authenticate, configure itself, and join the VeilNet fabric — no manual registration or YAML needed.

🧩 Convert to Docker Compose or Kubernetes #

You can easily convert the above command into a docker-compose.yml for repeatable deployment, or into Kubernetes manifests using Kompose.

The container requires --privileged mode because it needs permission to create and manage a layer 3 TUN (network tunnel) interface. This virtual network interface is essential for the portal to operate at the IP layer, enabling it to route traffic securely through the VeilNet fabric. The TUN interface must be added directly into the host’s network stack so the container can inject and receive raw IP packets, just like a traditional VPN gateway. Without elevated privileges, the container would not be able to perform these low-level network operations.

However, due to containerization, the TUN interface exists only within the network namespace of the container itself. It is not directly visible from the host, nor does it alter the host’s default routing table or interfere with normal host networking. This ensures safe operation without impacting other network processes running on the host.