API reference

Available Limited beta

The platform exposes two protocols today: an HTTP webhook that ingests DHCP lease events, and a gRPC method that allocates subnets.

Back to Developers

The lease webhook is the production ingestion path and the most complete surface in the platform.

  • Available 3 items Works today in the private beta.
  • In development 5 items Being built. Not callable yet.
  • Planned 3 items Designed, not started.

Lease ingestion path

The path one DHCP lease event takes through the webhook. Authentication failures never reach storage, and the sender is told the event is safe only after it is committed.

DHCP lease event ingestion

Six stages. The endpoint answers only after stage three, so a 202 means the event is durable.

  1. Wired

    A Kea DHCP server posts one lease event per request.

    • POST /api/v1/webhooks/dhcp/lease
  2. Wired

    The timestamp window is checked first. The HMAC-SHA256 signature is then compared in constant time.

    • Any failure: identical 401
  3. Wired

    Storage is idempotent on the pair (tenant, event id), so a retried event is recorded once.

    • key: (tenant, event id)
  4. Wired

    The endpoint answers only after the event is committed. A 202 means the event is durable.

    • 202
    • 202 (duplicate)
    • 503 + Retry-After
  5. Wired

    Workers claim committed events and write the lease, then mark the DNS record that depends on it as needing work. This stage touches only the relational store.

    • lease written
    • dns marked dirty
  6. Wired

    A separate pass picks up the marked records, compares what should exist against what is already published, and writes the forward and reverse entries.

    • forward record
    • reverse record

Endpoints

POST/api/v1/webhooks/dhcp/lease

HTTP Available

Ingests a DHCP lease event from a Kea DHCP server.

A Kea DHCP server posts one lease event per request. The endpoint answers only after the event is committed, so a 202 means the event is durable, not merely received.

Authentication

HMAC-SHA256

Requests are signed, not authenticated with a bearer token.

  • The sender computes the MAC over the timestamp and the raw request body joined by a period, and sends it with a key id so keys can be rotated.
  • The signature is compared in constant time.
  • The request timestamp must fall inside a freshness window. That check runs before the signature check.
  • The tenant named in the event must match the tenant that the signing key belongs to.

Parameters

  • event id UUID required

    Identifies the event. Storage is idempotent on the pair (tenant, event id).

    Constraint Must be a UUID. Reuse the same id when you retry the same event.

    Why A retried delivery is recorded once. That makes it safe for a sender to retry after a timeout without knowing whether the first attempt landed.

  • event timestamp integer, milliseconds required

    When the lease event happened.

    Constraint Milliseconds. May not be in the future.

    Why A future timestamp means a wrong clock on the sender, and accepting it would put events out of order in the lease history.

  • MAC address string required

    Hardware address of the leased host.

    Constraint Any common formatting is accepted. It is canonicalised before storage.

    Why Formatting differences (case, separators) would otherwise create duplicate hosts for one device.

  • tenant UUID required

    The tenant the event belongs to.

    Constraint Must match the tenant that the signing key belongs to.

    Why The key is the authority. A sender holding one tenant's key cannot write events into another tenant.

Documented at beta access

Not published on this page.

  • Names of the signature, timestamp and key id headers
  • Encoding of the signature
  • Freshness window duration
  • Request body size cap
  • Complete event schema beyond the fields above

Behavior

  • Freshness is checked before the signature

    A request outside the freshness window is rejected before any MAC is computed.

    Why A replayed request is turned away cheaply, so replay traffic cannot be used to burn compute on signature checks.

  • Constant-time comparison

    The received signature is compared to the expected one in constant time.

    Why A comparison that returns at the first differing byte leaks, through timing, how much of a forged signature was correct.

  • Identical 401 for every authentication failure

    Every authentication failure returns the same 401 with no detail about which check failed.

    Why Distinct errors for a bad key id, a stale timestamp and a bad MAC would let a caller probe each one separately.

  • Body size cap

    The request body has a size cap. The value is documented at beta access.

  • Durable before acknowledged

    The endpoint answers only after the event is committed to storage.

    Why The sender can delete its copy once it sees a 202, because a 202 means the event is safe.

Responses

  • 202

    Accepted. The event is committed.

    What to do Treat the event as delivered.

  • 202 (duplicate)

    Accepted with a duplicate indication: this event id was already stored for the tenant.

    What to do Treat the event as delivered. Nothing was written twice.

  • 409

    Conflict.

    What to do Do not retry blindly. Check the event against what is already stored.

  • 401

    Authentication failed. The body carries no detail, by design.

    What to do Check the key id, the signing key, the timestamp and the signed bytes on your side.

  • 503

    Storage is unavailable.

    Header Retry-After

    What to do Wait for the Retry-After interval, then retry with the same event id.

Retry guidance

  • On 503, honour Retry-After

    Wait at least as long as the Retry-After header says before the next attempt.

  • On a network timeout, retry with the same event id

    You cannot know whether the first attempt committed. Resend the identical event with the same event id.

    Why Storage is idempotent on (tenant, event id), so if the first attempt landed, the retry is recorded as a duplicate and nothing is written twice.

Examples

Signature input text, illustrative
signed_bytes = timestamp + "." + raw_request_body
mac          = HMAC_SHA256(signing_key, signed_bytes)
Illustrative. Sign the raw bytes you send, not a re-serialised copy. The header names and the MAC encoding are documented at beta access.
Request shape http, illustrative
POST /api/v1/webhooks/dhcp/lease HTTP/1.1
Content-Type: application/json
<key id header>: <KEY_ID>
<timestamp header>: <TIMESTAMP>
<signature header>: <MAC>

{ "event_id": "<UUID>", "tenant": "<UUID>", "mac": "<MAC_ADDRESS>", "ts": <MILLISECONDS>, ... }
Illustrative. Placeholders stand for values documented at beta access. Field names in the body are illustrative.

GET/healthz

HTTP Available

Liveness probe.

Reports that the process is alive and answering requests.

Behavior

  • Process liveness only

    This is not a dependency health check. A success does not mean the database or the graph store is reachable.

    Why A liveness probe that depends on the database turns a database outage into a restart loop of healthy processes. Keep the two questions separate.

Responses

  • 200

    The process is alive.

    What to do Use it for container liveness. Do not use it to infer that storage is reachable.

Examples

Probe bash, illustrative
curl -i https://<host>/healthz
Illustrative.

RPCPrefixService.AllocateNextFreeSubnet

gRPC Available

Allocates the next free subnet inside a tenant's address space.

Given a tenant's address space, the method finds the next free subnet and allocates it.

The gRPC port is not published to the public internet. Callers reach it from inside the deployment network.

Authentication

API key, omni_ bearer token or JWT

Exactly one credential is accepted per call.

  • Supply an API key header, an omni_-prefixed bearer token, or a JWT. A call that carries more than one credential is refused.
  • Each method has a required scope. This method needs a prefix write scope.
  • API keys are rate limited.
  • The verified tenant is taken from the credential and stamped on the request context.

Parameters

  • tenant UUID optional

    Optional. If the request body names a tenant, it must match the tenant on the credential.

    Constraint UUID. A mismatch with the credential's tenant refuses the call.

    Why The credential is the authority, never the payload. If a body field could override the credential, any caller could name another tenant.

  • site UUID required

    The site the subnet is allocated for.

    Constraint UUID, validated before any query runs.

    Why Validating the shape first means malformed input never reaches the database.

  • vrf UUID required

    The VRF whose address space is searched.

    Constraint UUID, validated before any query runs.

    Why Same reason as site: reject malformed input at the edge.

Documented at beta access

Not published on this page.

  • Remaining request fields (for example the requested subnet size)
  • Credential header names
  • Scope names
  • API key rate limits

Behavior

  • No double allocation

    The allocation takes a transaction-scoped advisory lock on the tenant's address space. Two concurrent allocations cannot hand out the same subnet.

    Why Finding "the next free subnet" is a read followed by a write. Without a lock, two callers can read the same answer and both write it.

  • Credential over payload

    The tenant comes from the verified credential. A tenant named in the body must match it or the call is refused.

    Why Trusting the payload would let a valid credential for one tenant act on another.

  • Database-enforced isolation

    Every query runs under PostgreSQL row-level security, as a role that cannot bypass it, with the tenant set for the transaction.

    Why Isolation is a property of the database, not of every query remembering a WHERE clause. A forgotten filter in application code still returns nothing from other tenants, because the database does not show those rows.

Responses

  • OK

    A subnet was allocated.

    What to do Use the returned prefix.

  • INVALID_ARGUMENT

    A tenant, site or VRF is not a valid UUID, or the body tenant does not match the credential.

    What to do Fix the request. Retrying unchanged will fail again.

  • UNAUTHENTICATED / PERMISSION_DENIED

    No valid credential, more than one credential, or the scope is missing.

    What to do Send exactly one credential that carries the prefix write scope.

Examples

Call shape text, illustrative
PrefixService.AllocateNextFreeSubnet(
  site = "<SITE_UUID>",
  vrf  = "<VRF_UUID>",
  ...  = <documented at beta access>
)
credential: exactly one of API key | omni_ bearer token | JWT
Illustrative. Illustrative. The tenant is read from the credential, so omit it from the body or make it match.

Not yet available

None of these can be called today.

REST IPAM API

In development

An HTTP interface for IP address management. Not callable yet.

Prefix search by name

In development

Find a prefix by its name. Not callable yet.

Semantic or natural-language prefix search

In development

Describe a prefix in words and find it. Not callable yet.

VRF management methods

In development

Create and manage VRFs through the API. Not callable yet.

User and session identity

In development

Interactive user sessions. Today there are machine credentials, API keys and JWTs, and no interactive user sessions.

Tenant self-service signup

Planned

Designed, not started.

Device discovery

Planned

Designed, not started.

Alerting and webhook fan-out for outbound events

Planned

Designed, not started.

Get beta access

Full request and error contracts are documented at beta access.

Join the beta