// API REFERENCE

IPAuth API v1

A REST API for managing your IPAuth pairs and access groups programmatically. Base URL: https://thrivesecurity.net/api/v1. Machine-readable spec: openapi.json.

Authentication: two factors, always

Every request needs both:

Factor 1 — the key. Send Authorization: Bearer ipa_….
Factor 2 — the origin. Your source IP must be on the key's origin allowlist (single IPs or CIDR blocks). Fail-closed: a key with no allowed origin authenticates from nowhere.

A leaked key is useless from an IP you didn't authorize. Keys are created in Account → API keys, gated by a fresh TOTP code. They are never minted via the API.

RECURSIVE LOCKDOWN

When you mint a key you can tick "Lock to a roving IP tracked by IPAuth." We hand you a bookmark alongside the key. Give both to the consuming server: it reports its IP through the bookmark (the normal IPAuth way), and the key then authenticates only from whatever IP that bookmark currently reports. The allowed origin follows the server automatically, and a stale IP (older than 24h) stops authorizing on its own.

Scopes

Keys carry scopes: account.read, account.write, pairs.read, pairs.write, groups.read, groups.write. A .write scope implies the matching .read. Read-only keys hold only .read scopes.

Responses

Success responses use an envelope; errors use RFC 7807 problem details with a stable type slug. Both carry a request_id.

{
  "data": { ... },
  "meta": { "request_id": "req_…", "timestamp": "2026-06-01T12:34:56+00:00" }
}

Endpoints

GET	/account Account info + resource counts	account.read
GET	/account/keys List your API keys (metadata only)	account.read
DELETE	/account/keys/{id} Revoke a key	account.write
GET	/account/audit?limit=N Recent audit events	account.read
GET	/pairs List pairs (a pair is a server)	pairs.read
POST	/pairs Create a pair → returns server_key once	pairs.write
GET	/pairs/{id} Get a pair	pairs.read
PATCH	/pairs/{id} Update name / contact_email	pairs.write
DELETE	/pairs/{id} Soft-delete a pair	pairs.write
GET	/groups List access groups (allowlists)	groups.read
POST	/groups Create a group	groups.write
GET	/groups/{id} Group detail + members	groups.read
DELETE	/groups/{id} Delete a group	groups.write
GET	/groups/{id}/ips Live IP allowlist for the group	groups.read
POST	/groups/{id}/members Add a pair {pair_id}	groups.write
DELETE	/groups/{id}/members/{pairId} Remove a pair	groups.write

Quickstart

# Whoami
curl -s https://thrivesecurity.net/api/v1/account \
  -H "Authorization: Bearer $IPAUTH_API_KEY"

# Register a server (creates a pair; server_key returned once)
curl -s https://thrivesecurity.net/api/v1/pairs \
  -H "Authorization: Bearer $IPAUTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ops-vps-1"}'

# Read a group's live IP allowlist (feed into ufw / NOC / Cloudflare)
curl -s https://thrivesecurity.net/api/v1/groups/7/ips \
  -H "Authorization: Bearer $IPAUTH_API_KEY"

Run from an IP on the key's origin allowlist, or you'll get a 403 forbidden_origin. Rate limits apply per key and per IP; a 429 includes a Retry-After header.