Edge Proxy

Route a subdomain through the edge proxy to an external upstream server. All requests to slug.domain are forwarded to the configured target URL.

A target must be proven before it can be routed. You must verify ownership of the target (see Verify target ownership) before creating or updating a proxy — create/update reject an unverified target with 403 target_unverified.

How it works

Verify ownership of the target (ACME-style proof-of-control)
Create a proxy record specifying a slug, optional domain, and the verified target URL
An etcd route is registered (pinned to the verified IP) so the edge proxy forwards traffic
All requests to https://slug.domain are reverse-proxied to the target

The edge proxy handles TLS termination, header forwarding (X-Forwarded-For, X-Forwarded-Proto, Host), and automatic retries.

Verify target ownership

Before a target can be routed, prove you control it. This is pull-based: you serve a one-time token at a well-known path on the target, and Oblien fetches it over an SSRF-safe, IP-pinned connection (the target never calls you). On success the route is pinned to the validated IP, so DNS rebinding can't redirect it inward.

1. Request a challenge

POST /edge/verifications
Content-Type: application/json

{ "target": "https://internal-staging.example.com:8080" }

Returns the token and the path to serve it at:

{
  "success": true,
  "verification": {
    "id": 7,
    "target": "https://internal-staging.example.com:8080",
    "status": "pending",
    "method": "http",
    "path": "/.well-known/oblien-proxy-challenge/9f3c…",
    "token": "9f3c…",
    "instructions": "Serve the exact text \"9f3c…\" (HTTP 200) at /.well-known/oblien-proxy-challenge/9f3c… …"
  }
}

2. Serve the token — make the target return the exact token text (HTTP 200) at path.

3. Check — Oblien fetches and validates it:

POST /edge/verifications/:id/check

{ "success": true, "verification": { "id": 7, "status": "verified", "validated_ip": "203.0.113.45", "expires_at": "2026-09-18 10:00:00" } }

A verification is valid for 90 days and is auto-renewed before expiry; if a target can no longer be proven, its proxies are disabled.

List / delete verifications

GET    /edge/verifications
DELETE /edge/verifications/:id

The verification check is rate-limited (it triggers an outbound request) and a single challenge caps total failed attempts — re-request the challenge to reset.

List proxies

GET /edge/proxies

curl "https://api.oblien.com/edge/proxies" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "success": true,
  "proxies": [
    {
      "id": 1,
      "name": "staging-api",
      "slug": "staging-api",
      "domain": "edge.example.com",
      "url": "https://staging-api.edge.example.com",
      "target": "https://internal-staging.example.com:8080",
      "status": "active",
      "created_at": "2026-03-12T10:00:00Z"
    }
  ]
}

Create a proxy

POST /edge/proxies
Content-Type: application/json

{
  "name": "staging-api",
  "slug": "staging-api",
  "domain": "edge.example.com",
  "target": "https://internal-staging.example.com:8080"
}

curl -X POST "https://api.oblien.com/edge/proxies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"staging-api","slug":"staging-api","domain":"edge.example.com","target":"https://internal-staging.example.com:8080"}'

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Display name (max 100 chars)
`slug`	string	Yes	Subdomain slug (lowercase, alphanumeric + hyphens)
`domain`	string	No	Base domain. Defaults to the platform default domain. Custom/wildcard domains require an entitlement granted to your account.
`target`	string	Yes	Upstream URL (`http://` or `https://`). Must already be verified — see Verify target ownership.

Custom domains must be ones you're entitled to. Use the Domains API to register and verify domains first; otherwise omit domain to use the platform default.

Response

{
  "success": true,
  "proxy": {
    "id": 1,
    "name": "staging-api",
    "slug": "staging-api",
    "domain": "edge.example.com",
    "url": "https://staging-api.edge.example.com",
    "target": "https://internal-staging.example.com:8080",
    "status": "active"
  }
}

Update a proxy

Update name, slug, or target URL. Slug and target changes update the etcd route atomically.

PUT /edge/proxies/:id
Content-Type: application/json

{ "name": "new-name", "target": "https://new-upstream.example.com" }

Enable / Disable

Toggle a proxy without deleting it. Disabling removes the etcd route (traffic stops), enabling re-creates it.

POST /edge/proxies/:id/enable
POST /edge/proxies/:id/disable

Delete a proxy

Removes the etcd route and DB record permanently.

DELETE /edge/proxies/:id

Target restrictions

The target URL is validated to prevent SSRF. The following are blocked:

Private IPs: 10.x.x.x, 172.16–31.x.x, 192.168.x.x
Loopback: 127.x.x.x, localhost, ::1
Link-local: 169.254.x.x
Unspecified: 0.x.x.x
Platform domains: *.oblien.com

Only http:// and https:// protocols are allowed.

On this page