Private Endpoints

Private endpoints let you access NFYio services (storage, agents, API gateway) using private IP addresses within your VPC. Traffic never leaves your private network, improving security and reducing exposure to the public internet.

Why Private Endpoints?

• No public exposure — Services are reachable only from within your VPC
• Lower latency — Traffic stays on the NFYio backbone
• Compliance — Meet requirements for data not traversing the public internet
• Simplified security — No need to allow public IP ranges in firewall rules

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    VPC (10.0.0.0/16)                        │
│                                                             │
│  ┌─────────────┐         ┌─────────────────────────────┐   │
│  │ Your App    │         │  Private Endpoint            │   │
│  │ 10.0.2.50   │────────►│  storage.internal → 10.0.2.100 │   │
│  └─────────────┘         │  agents.internal → 10.0.2.101  │   │
│                          │  api.internal → 10.0.2.102     │   │
│                          └─────────────────────────────┘   │
│                                        │                    │
└────────────────────────────────────────┼────────────────────┘
                                         │
                                         ▼
                              ┌──────────────────────┐
                              │  NFYio Services      │
                              │  (internal network)  │
                              └──────────────────────┘

Supported Services

Service	Endpoint Type	Default Hostname	Ports
Storage (S3)	Interface	storage.nfyio.internal	7007, 443
Agent Service	Interface	agents.nfyio.internal	7010, 443
API Gateway	Interface	api.nfyio.internal	3000, 443
PostgreSQL	Interface	postgres.nfyio.internal	5432
Redis	Interface	redis.nfyio.internal	6379

Creating a Private Endpoint

Via Console

1. Go to Networking → VPC → Endpoints
2. Click Create Endpoint
3. Select the service (e.g., Storage)
4. Choose your VPC and subnet
5. Optionally specify a security group
6. Click Create

Via API

curl -X POST https://api.yourdomain.com/v1/vpc-endpoints \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "storage-private",
    "service": "storage",
    "vpc_id": "vpc_abc123",
    "subnet_ids": ["subnet_priv_1", "subnet_priv_2"],
    "security_group_ids": ["sg_private_ep"]
  }'

Response:

{
  "id": "vpcpe_xyz789",
  "name": "storage-private",
  "service": "storage",
  "vpc_id": "vpc_abc123",
  "private_ip": "10.0.2.100",
  "dns_name": "storage.vpcpe_xyz789.nfyio.internal",
  "status": "available",
  "created_at": "2026-03-01T12:00:00Z"
}

VPC Endpoint Policies

Control which principals and actions are allowed through the endpoint using endpoint policies.

Example: Restrict to Specific Buckets

{
  "Version": "2026-03-01",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:nfyio:s3:::production-bucket/*",
        "arn:nfyio:s3:::production-bucket"
      ]
    }
  ]
}

Example: Deny Public Access

{
  "Version": "2026-03-01",
  "Statement": [
    {
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:PutObjectAcl",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "s3:x-amz-acl": "public-read"
        }
      }
    }
  ]
}

Applying a Policy

curl -X PUT https://api.yourdomain.com/v1/vpc-endpoints/vpcpe_xyz789/policy \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": "{\"Version\":\"2026-03-01\",\"Statement\":[...]}"
  }'

DNS Configuration

Private endpoints create DNS records in your VPC’s private hosted zone. Resolve the service hostname to the private IP:

# From within the VPC
nslookup storage.vpcpe_xyz789.nfyio.internal
# Returns: 10.0.2.100

For simpler hostnames, create a CNAME or use your own DNS:

storage.internal  CNAME  storage.vpcpe_xyz789.nfyio.internal

Using Private Endpoints in Code

AWS SDK (S3)

const { S3Client } = require('@aws-sdk/client-s3');

const client = new S3Client({
  endpoint: 'https://storage.vpcpe_xyz789.nfyio.internal:443',
  region: 'us-east-1',
  forcePathStyle: true,
});

Agent API

const response = await fetch('https://agents.vpcpe_xyz789.nfyio.internal:443/v1/chat', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Hello', thread_id: 'thread_123' }),
});

Security Groups

Create a security group for private endpoints that allows traffic only from your application subnets:

{
  "inbound": [
    {
      "protocol": "tcp",
      "port_range": "443",
      "source": "10.0.2.0/24"
    },
    {
      "protocol": "tcp",
      "port_range": "7007",
      "source": "10.0.2.0/24"
    }
  ]
}

Best Practices

1. Use private endpoints in production — Avoid exposing services on public IPs
2. Restrict with endpoint policies — Limit actions and resources
3. Monitor endpoint metrics — Track connection count and bandwidth
4. Multi-AZ — Create endpoints in multiple subnets for high availability

Next Steps

• VPC — VPC setup and CIDR planning
• Security Groups — Endpoint security group configuration
• Networking API Reference — Full endpoint API