Platform reference

HeyValue Provisioning API

The provisioning API creates and configures your customers and the products they use, through one API-first contract. It covers accounts, companies, licensing and entitlements, and the Shield DNS-security product for the HeyValue tenant.

How the pieces fit

An Envoy API gateway fronts every product service on one /v1/* surface. Each request passes a three-stage, fail-closed policy chain before it reaches a service:

Client ──▶ Gateway ──▶ [1] Authenticate (JWT)  ──▶ [2] Authorize (OPA)  ──▶ [3] License (entitlement) ──▶ Service
          api.heyvalue.com     realm pyme-heyvalue      ownership / role         plan / quota / usage        accounts · licensing · shield

The gateway verifies the caller's token, injects tenant identity as headers, and only then routes to accounts-api, licensing-api, or shield-api.

Base URL & environments

All paths are relative to the tenant's gateway host. For HeyValue:

Authentication

The platform uses OpenID Connect (Keycloak). Obtain a token from the HeyValue realm and send it as a bearer token; the gateway validates it, runs authorization and licensing, then injects verified tenant identity to the upstream service.

curl https://api.heyvalue.com/v1/shield/service \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-TARGET-COMPANY-ID: 4c1e…company-uuid"

Three authentication planes

Conventions

Versioning. Path-based; every endpoint lives under /v1. Content type. Requests and responses are JSON (application/json).

Response envelope

Shield service responses are wrapped in a fixed envelope. data carries the payload, errors is null on success, and status mirrors the HTTP status code.

{
  "data":   { "…": "…" },
  "errors": null,
  "status": 200
}

Many mutating Shield endpoints return a bare boolean payload on success:

{ "data": true, "errors": null, "status": 200 }

Identity headers

Errors & status codes

Errors use the same envelope with a populated errors array. Each entry has exactly three fields — message, field, ref. There is no code or details field; the machine-readable status is the numeric status.

{
  "data": null,
  "errors": [
    { "message": "non zero value required", "field": "company_id", "ref": "" }
  ],
  "status": 400
}

How provisioning works

Provisioning is event-driven. Creating a company automatically materializes its licensing entitlements; enabling a product then configures the product service. The gateway coordinates a two-phase commit so metered entitlements (like device seats) are counted exactly once.

1. Create the company
   POST /v1/companies. The gateway's licensing check reserves any consumed entitlement and flags a post-response callback.
2. Auto-provision entitlements
   On 201, the gateway calls licensing back; licensing runs resetCompany(company_id, tenant_id) — writing the company's per-service config and seeding limits from the tenant defaults.
3. Enable a product
   An admin PUTs the company's Shield service config. Licensing then calls Shield: POST /v1/service {company_id, enabled, plan} to provision the subscription.
4. Provision devices
   Create devices (or short-code links) under the company, then deliver a DoH or WireGuard profile to each device.
5. Commit the reservation
   The gateway posts the upstream result to POST /v1/authorize/response; licensing confirms the reservation on success or rolls it back on failure.

Accounts & Companies

Handled by accounts-api. Companies model the tenant's customers as a hierarchy; accounts are end users, each mirrored into the tenant's Keycloak realm on creation.

Create a customer company. A 201 here is what triggers automatic licensing provisioning (see How provisioning works).

curl -X POST https://api.heyvalue.com/v1/companies \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "pymeheyvalue",
    "reference_id": "acme-001",
    "name": "Acme Ltd"
  }'

{
  "id": "4c1e…",
  "tenant_id": "pymeheyvalue",
  "reference_id": "acme-001",
  "name": "Acme Ltd",
  "membership": [],
  "path": "…",
  "created_at": "2026-07-08T10:00:00Z"
}

Licensing & entitlements

Handled by licensing-api under /v1/licensing. It stores the tenant's service catalog and each company's effective entitlements, and acts as the gateway's real-time entitlement check.

{
  "name": "shield",
  "available": true,
  "enabled": true,
  "limits":   { "shield_devices_per_company": { "value": 5, "usage": 2 } },
  "features": { "shield_safe_search": { "enabled": true } },
  "plans": {
    "available": ["basic","family_parental","business_productivity","faithguard","parental","school"],
    "current":   "family_parental"
  }
}

Shield · Service lifecycle

The /v1/shield/service endpoints enroll, plan-switch, suspend, and remove a company's Shield subscription. GET/filtering/internet-access read the company from the X-TARGET-COMPANY-ID header; POST/DELETE take company_id in the body.

{
  "company_id": "4c1e…",
  "tenant_id": "pymeheyvalue",
  "plan": "family_parental",
  "enabled": true,
  "filtering_active": true,
  "suspended_until": null,
  "internet_access_filtering_active": true,
  "internet_access_suspended_until": null
}

curl -X POST https://api.heyvalue.com/v1/shield/service \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "X-TENANT-ID: pymeheyvalue" \
  -H "Content-Type: application/json" \
  -d '{ "company_id": "4c1e…", "enabled": true, "plan": "family_parental" }'

Shield · Device provisioning

Devices live under a company. Create a device directly (server-generated identity) or issue a short-code link that a device redeems at setup. Both paths converge on delivering a filtering profile (DoH or WireGuard) and, for managed clients, a device auth token.

{
  "id": "dev-uuid",
  "tenant_id": "pymeheyvalue",
  "company_id": "4c1e…",
  "name": "Kids iPad",
  "type": "ios",
  "connection_method": "doh",
  "short_code": "K7Q2ABX",
  "dns_provisioning_endpoint": "https://K7Q2ABX.dns.heyvalue.com/dns-query",
  "dns_server_addrs": ["…"],
  "created_at": "2026-07-08T10:05:00Z"
}

{
  "device_id": "dev-uuid",
  "timestamp": 1751971200,
  "signature": "base64url(R||S)"
}

{ "token": "eyJhbGciOiJFUzI1Ni…" }

[Interface]
Address = 10.x.y.z/32
DNS = 10.7.0.1
PrivateKey = <device private key>

[Peer]
PublicKey = <WG_SERVER_PUBLIC_KEY>
Endpoint = dns.heyvalue.com:51820
AllowedIPs = 10.7.0.0/16
PersistentKeepalive = 25

Data models

Profile & ServiceStatus

The company's Profile is the source of truth for subscription state; ServiceStatus (returned by GET /service) is a computed projection of it.

Device

Reference

Plans

Plan names accepted by the Shield subscription (from the licensing catalog default):

Safe-search providers

HeyValue tenant fact sheet

Concrete configuration values for the HeyValue tenant, used throughout the examples above.

End-to-end: provisioning Shield for a HeyValue customer

A complete worked flow from a new customer to a filtered device.

1. Create the company
   POST /v1/companies with tenant_id: pymeheyvalue. Licensing auto-provisions the company's entitlements on 201.
2. Enable Shield with a plan
   PUT /v1/licensing/companies/{cid}/services/shield/config with enabled: true and plans.current. Licensing calls Shield POST /v1/service.
3. Create a device link
   POST /v1/shield/devices/link → returns a 6-digit code the user enters in the HeyValue app.
4. Device enrolls
   The app submits the device's P-256 public key to POST /v1/shield/devices/link/{code}?tid=pymeheyvalue, then mints a token via POST /v1/shield/devices/token.
5. Deliver the filtering profile
   GET …/doh_profile (signed for dns.heyvalue.com) or …/vpn_profile. The device is now filtered at the HeyValue anycast edge.

curl -X PUT https://api.heyvalue.com/v1/licensing/companies/$CID/services/shield/config \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "name": "shield",
      "available": true,
      "enabled": true,
      "limits":   { "shield_devices_per_company": { "value": 5 } },
      "features": { "shield_safe_search": { "enabled": true } },
      "plans":    { "available": ["basic","family_parental"], "current": "family_parental" }
    }
  }'