API reference
Everything the console does goes through an HTTP API you can call yourself: from a cron job, a deployment script or an internal tool. This page covers the authorization model, every endpoint, certificate issuance, business metadata, subdomain checks and the OpenAPI description.
Authorization model
api_key ──< grant >── domain
│
└── scopes[]| Scope | Allows |
|---|---|
cert:read | Read certificates and their events |
cert:issue | Issue |
cert:renew | Renew |
cert:revoke | Revoke / delete |
cert:export | Download the private key (on top of read) |
dns:read | List the zone's records |
dns:write | UPSERT / DELETE records |
admin:* | Everything, on every domain, plus the console |
A key with no grant can do nothing. Rights are per domain: the NAS's key cannot issue for the build server's domain. Keys are managed in Keys & access.
Two separate mechanisms
| Web console | API | |
|---|---|---|
| Credential | email + password | API key |
| Storage | argon2id | sha256 |
| Transport | httpOnly / SameSite=lax cookie | Authorization header |
The password protects a low-entropy secret chosen by a human: it needs a slow KDF. An API key carries 256 bits of CSPRNG entropy — there is nothing to brute-force, so sha256 is enough and stays fast on every request.
A nonexistent account and a wrong password take the same amount of computation: accounts cannot be enumerated through latency.
Key format
lc_<prefix8hex>_<secret base64url 32 bytes>The prefix is indexed and safe to display. A key supplied by the operator (ADMIN_API_KEY) can be any opaque string: its lookup prefix is derived from its own sha256, and both forms share the same index.
Two ways to authenticate
# 1. API key directly (handy for cron/curl)
curl -H "Authorization: Bearer lc_..." https://certs.example.com/api/v1/certificates
# 2. exchange it for a short-lived JWT (1 h), scopes embedded in the token
TOKEN=$(curl -s -X POST https://certs.example.com/api/v1/auth/token \
-H "Authorization: Bearer lc_..." | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" https://certs.example.com/api/v1/certificatesThe admin console uses an httpOnly + SameSite=lax session cookie carrying an equivalent JWT, obtained with email + password.
Endpoints
Authentication
GET /api/setup { setup_required: bool }
POST /api/setup create the admin account (once only)
POST /api/v1/auth/token API key -> JWTCertificates
GET /api/v1/certificates ?status= &domain= &expires_within_days= &limit= &metadata.<key>=
POST /api/v1/certificates 202 + Location
GET /api/v1/certificates/{id}
PATCH /api/v1/certificates/{id} update the metadata
DELETE /api/v1/certificates/{id} ?purge=true to erase the row
POST /api/v1/certificates/{id}/renew
GET /api/v1/certificates/{id}/bundle ?format=json|pem &include=fullchain,cert,chain,key
GET /api/v1/certificates/{id}/events ?stream=1 for SSESubdomains
GET /api/v1/subdomains/{fqdn} is this subdomain already taken?DNS
GET /api/v1/dns/records ?domain_id=
PUT /api/v1/dns/records
DELETE /api/v1/dns/records ?fqdn= &type= &values= &ttl=Miscellaneous
GET /api/v1/acme/account
GET /api/openapi.json OpenAPI 3.1 description (authenticated)
GET /api/healthz
POST /api/mcp MCP server for AI agentsThe MCP server is described in MCP server.
Administration (console session)
POST|GET|DELETE /api/admin/session email+password / whoami / logout
GET|POST /api/admin/providers ?force=true to save despite a failed test
POST /api/admin/providers/probe test credentials without storing them
PATCH|DELETE /api/admin/providers/{id}
GET /api/admin/providers/{id}/zones visible hosted zones
GET /api/admin/providers/{id}/policy full IAM policy (?zone_id= to add)
GET|POST /api/admin/domains
POST /api/admin/domains/preflight the checks of an add, without writing anything
DELETE /api/admin/domains/{id} ?force=true to delete it with its certificates
GET|POST /api/admin/keys
PATCH|DELETE /api/admin/keys/{id}
GET /api/admin/statsIssuing a certificate
curl -X POST https://certs.example.com/api/v1/certificates \
-H "Authorization: Bearer $TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'content-type: application/json' \
-d '{
"domains": ["nas.home.example.com"],
"key_type": "ec-256",
"auto_renew": true,
"renew_before_days": 30,
"webhook_url": "https://nas.home.example.com/hooks/cert",
"dns": { "create_record": true, "target_ip": "192.168.1.50", "ttl": 60 }
}'The response is an immediate 202 Accepted. Follow progress with:
curl -N -H "Authorization: Bearer $TOKEN" \
"https://certs.example.com/api/v1/certificates/$ID/events?stream=1"State machine:
pending → dns_propagating → validating → issued
↘ failed (exponential retry, 5 attempts)
issued → revoked | expiredBusiness metadata
Each subdomain carries a key/value map of strings, supplied by the calling system to tie it to its own context: tenant, environment, ticket, internal identifier.
curl -X POST …/api/v1/certificates -H "Authorization: Bearer $TOKEN" \
-d '{
"domains": ["nas.home.example.com"],
"metadata": { "tenant_id": "acme-corp", "env": "prod", "ticket": "OPS-1421" }
}'Updating — merge by default, replace to overwrite:
curl -X PATCH …/api/v1/certificates/$ID \
-d '{ "metadata": { "tenant_id": "other-corp" }, "mode": "replace" }'Filtering the list, one key at a time:
curl "…/api/v1/certificates?metadata.tenant_id=acme-corp"The filter is applied in the application, not in SQL: JSON operators differ between SQLite and Postgres and the column is indexed in neither, so there is nothing to gain by pushing it into the query.
Limits: 20 entries, keys of 64 characters in [A-Za-z0-9._:-], values of 512 characters, 4096 bytes once serialized. This is context, not a document store.
Checking whether a subdomain is taken
curl …/api/v1/subdomains/nas.home.example.com -H "Authorization: Bearer $TOKEN"{
"fqdn": "nas.home.example.com",
"available": false,
"managed_domain": "home.example.com",
"dns": {
"exists": true,
"managed": true,
"records": [{ "type": "A", "ttl": 60, "values": ["192.168.1.50"] }]
},
"certificate": { "id": "cert_…", "status": "issued", "days_remaining": 89, "metadata": {} },
"metadata": { "tenant_id": "acme-corp" }
}The two sources of truth are queried separately because they can diverge: a record can exist in the zone without local-cert knowing about it (created by hand, or by another tool), and a certificate can exist here with nothing published. available is true only if neither source knows the name and the zone was readable — an unreadable zone is reported in dns.error rather than letting the name pass as free.
Requires cert:read on the covering domain. The DNS half is not protected any further: it is public data, resolvable with dig by anyone.
OpenAPI documentation
The full OpenAPI 3.1 description is served at GET /api/openapi.json (authenticated — the schema maps the whole surface of an internal tool).
The console ships an explorer at /admin/api: endpoints grouped by tag, a filter, parameters and bodies pre-filled from the schema, the equivalent curl, and a Send button that actually runs the request from the browser with your session cookie.
Generation
The document is generated, never written by hand:
| Element | Source |
|---|---|
| Request bodies | the zod schemas the handlers validate against (src/lib/validation.ts) |
| Responses | src/lib/api/schemas.ts, tied to the runtime through z.infer |
| Operations | src/lib/api/routes.ts |
Conversion uses zod 4's z.toJSONSchema(). Constraints therefore come for free from the validators — the FQDN regex, the TTL bounds and the metadata lengths appear in the spec because they exist in the code.
Three guards, run by npm run openapi:check:
- Coverage — every App Router handler on disk must be in the registry, and vice versa. A route added without documentation fails the check.
- Input/output consistency — no response schema may differ between its input and output projections; the generator makes a single pass, which is only correct as long as that holds (a
.default()or a.transform()on a response would break the assumption). $refresolution — every reference must point to an existing component.
Typing closes the loop: serializeCert returns z.infer<typeof certificateSchema>, so changing the serialized shape without updating the published schema fails at compile time.
openapi:check ok — 30 operations over 19 paths, 36 component schemas, all $refs resolve.