Skip to content
local-cert
Browse the documentation

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

Model
api_key ──< grant >── domain
             │
             └── scopes[]
ScopeAllows
cert:readRead certificates and their events
cert:issueIssue
cert:renewRenew
cert:revokeRevoke / delete
cert:exportDownload the private key (on top of read)
dns:readList the zone's records
dns:writeUPSERT / 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 consoleAPI
Credentialemail + passwordAPI key
Storageargon2idsha256
TransporthttpOnly / SameSite=lax cookieAuthorization 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

API key
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

shell
# 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/certificates

The 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 -> JWT

Certificates

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 SSE

Subdomains

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 agents

The 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/stats

Issuing a certificate

shell
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:

shell
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 | expired

Business 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.

shell
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:

shell
curl -X PATCH …/api/v1/certificates/$ID \
  -d '{ "metadata": { "tenant_id": "other-corp" }, "mode": "replace" }'

Filtering the list, one key at a time:

shell
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

shell
curl …/api/v1/subdomains/nas.home.example.com -H "Authorization: Bearer $TOKEN"
response
{
  "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:

ElementSource
Request bodiesthe zod schemas the handlers validate against (src/lib/validation.ts)
Responsessrc/lib/api/schemas.ts, tied to the runtime through z.infer
Operationssrc/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:

  1. Coverage — every App Router handler on disk must be in the registry, and vice versa. A route added without documentation fails the check.
  2. 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).
  3. $ref resolution — 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.

npm run openapi:check
openapi:check ok — 30 operations over 19 paths, 36 component schemas, all $refs resolve.