Network

Configure network policies for your workspace - internet access, inbound/outbound firewall rules, private links between workspaces, and dedicated outbound IPs.

Get network

Get the current network configuration.

const network = await ws.network.get('ws_a1b2c3d4');

GET /workspace/:workspaceId/network

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "ip": "10.0.0.15",
  "gateway": "10.0.0.1",
  "public_access": false,
  "allow_internet": true,
  "ingress": [],
  "ingress_ports": [],
  "egress": [],
  "egress_ports": [],
  "outbound_ip": null,
  "private_links": []
}

Response fields

Field	Type	Description
`ip`	`string`	Workspace private IP address (use this for direct connections)
`gateway`	`string`	Network gateway
`public_access`	`boolean`	Whether public inbound traffic is allowed (required for gateway access)
`allow_internet`	`boolean`	Whether outbound internet is allowed
`ingress`	`string[]`	Allowed inbound source IPs (managed automatically via private links)
`ingress_ports`	`number[]`	Allowed inbound ports
`egress`	`string[]`	Allowed outbound hosts/CIDRs
`egress_ports`	`number[]`	Allowed outbound ports
`outbound_ip`	`string\|null`	Dedicated outbound IP if assigned
`private_links`	`object[]`	Linked workspaces with resolved IPs (see Private Links)

The ip field is the workspace's internal network address. You'll need this when making direct workspace-to-workspace calls. You can also get it from the raw token endpoint, which returns both the IP and the connection token in one call.

Update network

Partially update network policy. Only the fields you provide are changed.

await ws.network.update('ws_a1b2c3d4', {
  allow_internet: true,
  ingress_ports: [80, 443, 3000],
  egress: ['api.github.com', 'registry.npmjs.org'],
  public_access: false,
});

PATCH /workspace/:workspaceId/network

{
  "allow_internet": true,
  "ingress_ports": [80, 443, 3000],
  "egress": ["api.github.com", "registry.npmjs.org"],
  "public_access": false
}

curl -X PATCH "https://api.oblien.com/workspace/ws_a1b2c3d4/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_internet": true,
    "ingress_ports": [80, 443, 3000],
    "egress": ["api.github.com"]
  }'

Parameters

All fields are optional:

Parameter	Type	Description
`allow_internet`	`boolean`	Enable/disable outbound internet. Setting to `false` clears `egress`
`ingress_ports`	`number[]`	Allowed inbound ports (1–65535, max 50 entries)
`egress`	`string[]`	Allowed outbound hosts/CIDRs (max 50 entries, printable ASCII)
`public_access`	`boolean`	Allow public inbound traffic (required for gateway access)
`private_link_ids`	`string[]`	Workspace IDs to link - resolved to private IPs and added to firewall ingress (see Private Links)

Validation rules

Port numbers must be between 1 and 65535
Maximum 50 entries per list (ingress, egress, ingress_ports)
Hosts must be printable ASCII characters
Setting allow_internet: false forces egress: []
public_access: true adds the host keyword to the ingress list

Replace network

Replace the entire network policy. All fields not specified revert to defaults.

await ws.network.replace('ws_a1b2c3d4', {
  allow_internet: false,
  ingress_ports: [22],
  ingress: ['10.0.0.0/8'],
  egress: [],
  public_access: false,
});

PUT /workspace/:workspaceId/network

{
  "allow_internet": false,
  "ingress_ports": [22],
  "ingress": ["10.0.0.0/8"],
  "egress": [],
  "public_access": false
}

curl -X PUT "https://api.oblien.com/workspace/ws_a1b2c3d4/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_internet": false,
    "ingress_ports": [22],
    "ingress": ["10.0.0.0/8"],
    "egress": [],
    "public_access": false
  }'

Same parameters as Update, but this replaces the full policy.

Private links

Private links allow workspace-to-workspace communication over the internal network. By default, every workspace is network-dark - no inbound traffic is allowed from any source, including other workspaces in the same account. Private links explicitly whitelist specific workspaces.

When you set private_link_ids on a workspace, the platform resolves each workspace ID to its internal IP and adds it to the target's firewall ingress. The linked workspaces can then reach the target over the private 10.x.x.x network.

// Allow ws_caller to reach ws_target
await ws.network.update('ws_target', {
  private_link_ids: ['ws_caller'],
});

// Allow multiple workspaces
await ws.network.update('ws_target', {
  private_link_ids: ['ws_caller_1', 'ws_caller_2', 'ws_orchestrator'],
});

PATCH /workspace/:workspaceId/network

{
  "private_link_ids": ["ws_caller_1", "ws_caller_2"]
}

curl -X PATCH "https://api.oblien.com/workspace/ws_target/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "private_link_ids": ["ws_caller_1", "ws_caller_2"] }'

How it works

You provide workspace IDs (not raw IPs) in private_link_ids
The platform resolves each ID to its internal 10.x.x.x IP
Resolved IPs are added to the target workspace's firewall ingress list
The public_access state is preserved - private links don't affect gateway access
Only workspaces that successfully resolve to an IP are linked

Response

The update returns the resolved link IDs:

{
  "success": true,
  "private_link_ids": ["ws_caller_1", "ws_caller_2"]
}

Viewing linked workspaces

The GET /network response includes resolved private link details:

{
  "private_links": [
    {
      "id": "ws_caller_1",
      "ip": "10.40.0.5",
      "name": "my-agent",
      "image_logo": "node",
      "image_color": "#3C873A"
    },
    {
      "id": "ws_caller_2",
      "ip": "10.40.0.12",
      "name": "orchestrator",
      "image_logo": "python",
      "image_color": "#306998"
    }
  ]
}

Removing links

Set private_link_ids to an empty array to remove all links:

await ws.network.update('ws_target', {
  private_link_ids: [],
});

Private links are one-directional. Linking ws_caller → ws_target allows the caller to reach the target, but the target cannot reach the caller unless you also create a link in the other direction.

Private links are required for direct workspace-to-workspace access to the Internal API. Without a link, the target's firewall blocks the connection even if the caller knows the IP and has a valid token.

List available outbound IPs

Get all Zones IPs in the pool that can be assigned to a workspace as a dedicated outbound IP.

GET /zone/mine

curl "https://api.oblien.com/zone/mine" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "proxies": [
    { "ip": "203.0.113.50", "country_code": "US" },
    { "ip": "198.51.100.12", "country_code": "DE" }
  ]
}

Use any ip value from this list when calling Apply outbound IP below.

Apply outbound IP

Assign a dedicated outbound IP address to the workspace. All outbound traffic will route through this IP. Useful for whitelisting in third-party firewalls.

POST /workspace/:workspaceId/network/ip

{
  "ip": "203.0.113.50"
}

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/network/ip" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ip": "203.0.113.50" }'

Parameters

Parameter	Type	Required	Description
`ip`	`string`	Yes	Outbound IP from `GET /zone/mine`

Response

{
  "success": true,
  "ip": "203.0.113.50",
  "country_code": "US"
}

Errors

Code	Status	Cause
`ip_required`	400	`ip` field missing from request body
`invalid_zone_ip`	400	IP is not in the available pool
`zone_missing_host`	422	Zone configuration is incomplete
`pool_empty`	503	Egress zone temporarily unavailable

Learn more about networking concepts in Concepts: Networking.

On this page