Peerlify
All posts

Product · 5 min read

Launch: the Peerlify API and webhooks — on every plan

A scoped REST API over every network resource, and signed webhooks for the events that matter. Automate enrollment, manage access policy from code, and stream device and membership events into your own systems — included from free Personal through Enterprise.

I

Ivan Vyshniak

Product

Everything you can do to a network in the Peerlify console, you can now do with a token. Today we are shipping the public REST API (v1) and webhooks — and both are included on every plan, from free Personal through Enterprise.

Private networking is infrastructure, and infrastructure belongs in code. Enrolling a fleet, keeping access policy in a repo, reacting when a device goes stale — these are the things operators automate. So the primitives to automate them shouldn't sit behind an upgrade.

The API

The API is a plain JSON REST interface served from your console host under /api/v1. Every request and response is JSON, every mutation is written to the same audit log the console writes to, and every token is scoped to a single network — the one you were viewing when you minted it. You never pass a network ID; the token resolves it server-side.

A token can cover six resources:

  • Devices — list, approve pending enrollments, rename, tag, toggle key expiry, and remove.
  • Auth keys — mint reusable or single-use enrollment keys with auto-tags and expiry, for unattended peerlify login --auth-key=… provisioning.
  • Network — read and update network settings, and manage tag definitions.
  • Policy — GET/PUT the whole ACL document. A replace runs the policy's embedded ACL tests first and is rejected if any fail, so you can't push a policy that contradicts its own intent.
  • Users — list members, change roles, approve, and remove.
  • Webhooks — manage endpoints programmatically.

Tokens are scoped as resource:access (devices:write, policy:read, …); a token with no scopes has full access within its network, and :write always implies :read. Secrets — tokens, auth keys, webhook signing secrets — are shown exactly once at creation, so a leaked credential is revoked and replaced, never recovered. Owners, Admins and Network Admins create tokens and webhook endpoints.

bash
curl https://web.peerlify.com/api/v1/devices \
  -H "Authorization: Bearer papi_your_token_here"

Webhooks

Polling an API to find out that a device enrolled is the wrong shape. Webhooks turn the questions around: register an HTTPS endpoint, subscribe to the events you care about, and Peerlify POSTs you a signed payload the moment one fires.

The catalog covers the lifecycle you'd actually build on — device.created, device.approved, device.deleted, device.key_expiring, device.key_expired, user.approved, user.role_changed, user.removed, policy.updated, and network.updated. Wire device.created to a Slack channel so approvals never sit unseen; wire user.role_changed and policy.updated into your SIEM so the security team has a live feed of who can reach what.

Every delivery is signed. A Peerlify-Signature header (t=<timestamp>,v1=<hex>) carries a timestamp and an HMAC-SHA256 over <timestamp>.<raw body>, keyed with the endpoint's secret, so you can verify the callback came from us and reject stale replays. Failed deliveries retry with exponential backoff — 1, 2, 4, 8, then 16 minutes — and each carries a stable Peerlify-Delivery ID so your handler can dedupe.

Available now

Mint a token under Settings → Keys in the console, or manage webhook endpoints under Settings → Webhooks. Full request and response shapes, error codes, and a signature-verification snippet live in the API reference. No new tier, no add-on — it's part of every network.