The iRonShore Lighthouse API

Scripts, pipelines and other programs use the same API as the Lighthouse console, under /api/v1. Version 1 only grows: routes and fields are added, never removed or changed.

• API Explorer: https://<your server>/api/v1/docs (API next to Help at the top of every console page, opening in a tab of its own so the console page stays as it was), read from the OpenAPI 3.1 description at /api/v1/openapi.json. Each route has Try it, which sends the request from the browser as the person signed in to the console, or with an API token pasted at the top of the page. Import the OpenAPI file into Postman, a client generator or PowerShell tooling.
• Errors are {"error": "..."} with 400 (not valid), 403 (not allowed, naming the permission), 404 (not found, or not visible to the caller), 409, 422 (a template's policy) or 502 (the CA or mail server said no).
• A certificate the caller may not see answers 404, not 403, so its existence is not confirmed.
• Settings routes need the permission of their group: administrators (the whole Administrator profile everywhere, the Operator role in GET /me) and anyone given that group's permission everywhere. Connections (settings.connections): /settings/cas, adding, changing or deleting /templates and /facts, /settings/integrations, /settings/webhooks, /settings/log-destinations, /settings/ai-model, /settings/password-managers, /settings/secret-pointers, /outposts. People (settings.people): /access/..., every team, /settings/signin, /settings/mail, /settings/approval-email, /settings/message-wording, /settings/team-summaries. Bulk changes (settings.bulk): /drills, /ca-migrations, /moves. Logs (settings.logs): /settings/server-log, and reading /audit and /logs. Server (settings.server): /settings/general, /settings/site-name, /settings/banner, /settings/notice, /settings/weak-rules, /settings/crypto-policy, /settings/key-types, /settings/subject-defaults, /settings/pfx-downloads, /settings/key-encryption, /settings/personal-acme-keys, /settings/ai-suggestions, /settings/features/{key}, /settings/license, /settings/cleanup, /servers, PUT /dashboard-layout, GET /dashboard-layout/teams. GET /settings and GET /server answer anyone who opens any group. Anyone else gets 403 naming the permission. GET /me returns areas, the groups the caller opens (connections, people, bigjobs, records, server). Reading /templates, /facts, /authorities, /features and /banner stays open, since enrolling needs them, and the records /audit, /logs and /keys keep their own permissions too. settings.manage, access.manage and templates.manage are gone; a profile sent with them drops them.
• You give only what you hold, and never to yourself. Creating or changing a grant, profile, team's members, Spotlight's Who can use it, /access/automation, /access/new-people, an API token's profile, or a template's people, answers 403 when the caller does not hold what it gives, where it gives it (removing or narrowing access needs what it gives now). When the change names the caller (their account, a group of theirs, a team of theirs, or the token itself), it is not made: the answer is 202 Accepted with {"request": {...}, "waits": "..."}, and the change waits on Requests as a request of kind access for someone else who opens that group under Settings. Grants, team members, Spotlight shares, /access/automation entries and template people take until (UTC; it must be ahead), after which they stop counting and are removed within the hour.
• Lists show only what the caller sees: for anyone but an administrator, GET /owners lists the teams they are in and the teams owning certificates they see (another team with only its id and name; everyone given See certificates or Approve requests everywhere gets every team), GET /tags and GET /authorities only those on or behind certificates they see, GET /change-windows only their teams' windows, and every count is over the certificates they see. GET /templates lists only the templates opened to them, with only their own teams in teams and no people.
• Alerts are for administrators and people given an alerts permission: GET /alerts/recent needs See alerts (alerts.view; everywhere gives every alert, for some teams only alerts about those teams' certificates) or Create and change alerts (alerts.manage, every alert); anyone else gets 403. GET /jobs lists the alert jobs left from before 0.33.0 (expiry-alerts, weak-check) only to them, and changing, running or deleting one needs Create and change alerts, not Create and change jobs; POST /jobs adds no new one (400), since alerts are Pipelines now. The same two permissions open GET /pipelines with only the certificate.expiring and certificate.weak events and their Pipelines, and GET /pipelines/runs with only their runs (See alerts for some teams gets no runs); Create and change alerts also adds, changes, orders and deletes those Pipelines with tell and wait steps. No built-in profile but Administrator has either permission.
• Reports are for administrators and people given a reports permission: GET /reports, GET /reports/{kind} and GET /reports/{kind}/csv need See reports (reports.view; everywhere reports on every certificate, for some teams only on those teams' certificates and the Spotlights the caller may see) or Create and change reports (reports.manage, every certificate); anyone else gets 403. Saving, changing, deleting and sending saved reports needs Create and change reports. No built-in profile but Administrator has either permission.
• The Keeper's Log is for administrators, Settings, Logs and auditors: GET /audit (the Keeper's Log, Lighthouse's audit log) needs the Administrator profile, Read the logs (settings.logs) or Read the Keeper's Log (audit.view) everywhere; the built-in Auditor profile has the last. POST /audit/check checks every sealed entry against its seal and answers {ok, checked, sealedUpTo, waiting, checkedAt, problems: [{auditEventId, kind, what}], summary, keyMissing}, where kind is changed, removed or added. ?kind=sign-ins shows only sign-ins and sign-outs (sign-in, sign-out, sign-in-failed, sign-in-refused, first-sign-in, token-use), ?kind=settings only settings-change, whose details is JSON with before and after. A change through the API whose route wrote nothing is still recorded, as change with its method and path. To keep a copy outside Lighthouse, use log forwarding's audit stream.

Signing in

API tokens are for anything that runs unattended. On People & Access, under API tokens, choose New API token, give it a name such as deploy-pipeline, a lifetime (up to two years) and a profile, everywhere or for some teams. The secret is shown once; Lighthouse keeps only its hash.

Send it on every request:

Authorization: Bearer lh_...

A token is its own name, token:<name>. It can do only what is granted to that name on People & Access, exactly like a person: give it more with Grant…, or add token:<name> to a team as a member. Keeper's Log entries show it as token:<name>, with token-use the first time it is used after 8 quiet hours, and certificates it enrolls are owned by it and the team it enrolled for. New secret replaces the secret and keeps the grants; Remove stops it at once and removes its grants.

Too many bad tokens. An address that sends 20 unknown, removed or expired tokens in 5 minutes gets 429 Too Many Requests (with Retry-After) for every token, good ones too, until the 5 minutes pass. Requests with a good token are not limited; /mcp is, at 120 a minute per address.

Windows sign-in also works, for a script run by a person on a domain computer (Invoke-RestMethod -UseDefaultCredentials). Requests that change something then need the header X-Lighthouse: 1; with a token they do not.

In IIS, keep Anonymous Authentication on for the site (the default) beside Windows Authentication, so a request with a token reaches Lighthouse.

No session. Without a token or a session, the API answers 401 with the header X-Lighthouse-Sign-In: /signin. A request that carries X-Lighthouse-Console: 1, as the console and the API explorer send, gets 440 (Login Time-out) instead, with the same header: IIS adds its Windows challenge to every 401, and a browser would answer that with its own password box. Scripts should not send it. After a session timed out the header says why, such as /signin?signedOut=true&ended=idle (or ended=longest), and the console goes there.

Session timeouts. A browser session ends after Settings, Sign-in, Sessions' minutes without use (30 unless changed) and its longest session (12 hours). Every request with the session cookie counts as use unless it carries X-Lighthouse-Background: 1, which the console sends on what it reads by itself, such as Server Log's live lines; POST /me/active is the console saying someone is typing, clicking or scrolling. GET /me returns session (idleMinutes, warnSeconds, longestHours, endsAt). API tokens have no session and never time out this way.

Examples

PowerShell:

$h  = @{ Authorization = "Bearer $env:LIGHTHOUSE_TOKEN" }
$lh = "https://lighthouse.example.test/api/v1"

# What expires in the next 30 days, and who owns it
Invoke-RestMethod "$lh/certificates?expiring=30" -Headers $h | Select-Object displayName, daysLeft, owners

# Every certificate with no owner, 500 at a time (X-Total-Count says how many in all)
$offset = 0
do {
  $page = Invoke-RestMethod "$lh/certificates?rule=owner:none&sort=notAfter&offset=$offset&limit=500" -Headers $h -ResponseHeadersVariable rh
  $page | Select-Object displayName, notAfter
  $offset += 500
} while ($offset -lt [int]$rh["X-Total-Count"][0])

# Fill in a Fact on certificates that don't have it yet, from a CSV with columns thumbprint,costCenter.
# PUT .../facts replaces all of a certificate's facts, so send its current ones back with the new one.
$missing = Invoke-RestMethod "$lh/certificates?rule=$([uri]::EscapeDataString('not fact:Cost center'))&limit=2000" -Headers $h
$wanted  = @{}; Import-Csv costcenters.csv | ForEach-Object { $wanted[$_.thumbprint.ToUpper()] = $_.costCenter }
foreach ($c in $missing | Where-Object { $wanted.ContainsKey($_.thumbprint.ToUpper()) }) {
  $facts = @{}; $c.facts.PSObject.Properties | ForEach-Object { $facts[$_.Name] = $_.Value }
  $facts["Cost center"] = $wanted[$c.thumbprint.ToUpper()]
  Invoke-RestMethod "$lh/certificates/$($c.thumbprint)/facts" -Method Put -Headers $h -ContentType "application/json" -Body (@{ facts = $facts } | ConvertTo-Json)
}

# Enroll a CSR made on the server that will use the certificate
$body = @{ templateId = 3; team = 7; csr = Get-Content .\web01.csr -Raw } | ConvertTo-Json
Invoke-RestMethod "$lh/enroll" -Method Post -Headers $h -ContentType application/json -Body $body

# Run an installation's renewal job now
Invoke-RestMethod "$lh/jobs/12/run" -Method Post -Headers $h

# Keep an F5 BIG-IP client SSL profile's certificate current (administrators; Network appliances on).
# The password is stored on the server first: lh secret set appliance-password
$job = @{ name = "bigip01 www"; kind = "renew-appliance"; schedule = "daily 03:00"; autoRenew = "renew"
          parameters = @{ vendor = "f5"; host = "bigip01.example.test"; user = "lighthouse"; profile = "clientssl-www"
                          templateId = 3; servedHost = "www.example.test"; syncGroup = "failover-group" } } | ConvertTo-Json
Invoke-RestMethod "$lh/jobs" -Method Post -Headers $h -ContentType application/json -Body $job

# Keep SQL Server's certificate current (administrators); the instance restarts to take it, so give it a change window
$job = @{ name = "sql01 MSSQLSERVER"; kind = "renew-windows"; schedule = "daily 03:00"; autoRenew = "renew"; changeWindow = "sun 02:00-04:00"
          parameters = @{ host = "sql01.example.test"; use = "sql"; instance = "MSSQLSERVER"; templateId = 3 } } | ConvertTo-Json
Invoke-RestMethod "$lh/jobs" -Method Post -Headers $h -ContentType application/json -Body $job

# Keep an IIS site current, signing in as a separate install account rather than Lighthouse's own (administrators);
# its password is stored first on the server (lh secret set windows-web-servers) or, from an Outpost, in that Outpost's Secrets
$job = @{ name = "web01 Default Web Site"; kind = "renew-iis"; schedule = "daily 03:00"
          parameters = @{ host = "web01.example.test"; site = "Default Web Site"; templateId = 3
                          signInAs = "EXAMPLE\lh-install-web"; signInPasswordSecret = "windows-web-servers" } } | ConvertTo-Json
Invoke-RestMethod "$lh/jobs" -Method Post -Headers $h -ContentType application/json -Body $job

# Keep a Tomcat PFX on Windows current and restart Tomcat (administrators); the password is stored first: lh secret set installation-app01
$job = @{ name = "app01 Tomcat"; kind = "renew-windows-files"; schedule = "daily 03:00"
          parameters = @{ host = "app01.example.test"; format = "pfx"; pfxPath = "C:\Tomcat\conf\tls.pfx"; pfxPasswordSecret = "installation-app01"
                          service = "Tomcat9"; servedHost = "app01.example.test"; servedPort = 8443; templateId = 3 } } | ConvertTo-Json
Invoke-RestMethod "$lh/jobs" -Method Post -Headers $h -ContentType application/json -Body $job

# Add a HashiCorp Vault PKI CA (administrators only); the AppRole secret id goes to the secret store
$ca = @{ kind = "vault"; name = "Lab Vault"; apiKey = $env:VAULT_SECRET_ID
         settings = @{ url = "https://vault.example.test:8200"; mount = "pki_int"; authMethod = "approle"; roleId = "<role id>" } } | ConvertTo-Json
Invoke-RestMethod "$lh/settings/cas/test" -Method Post -Headers $h -ContentType application/json -Body $ca
Invoke-RestMethod "$lh/settings/cas" -Method Post -Headers $h -ContentType application/json -Body $ca

# Let a team's Installations renew by themselves (off, notify or renew; $null uses the global setting)
Invoke-RestMethod "$lh/owners/7/auto-renew" -Method Put -Headers $h -ContentType application/json -Body '{"autoRenew":"renew"}'

# Give a Spotlight to a person and a team (administrators only); the list replaces who may use it
$ro = (Invoke-RestMethod "$lh/access/profiles" -Headers $h | Where-Object builtIn -eq "read-only").id
$who = ConvertTo-Json -InputObject @(@{ principal = "EXAMPLElice"; profileId = $ro }, @{ team = 7; profileId = $ro })
Invoke-RestMethod "$lh/spotlights/12/access" -Method Put -Headers $h -ContentType application/json -Body $who

# Spotlights that need someone: expired or due within 7 days
Invoke-RestMethod "$lh/spotlights/health" -Headers $h | Where-Object status -eq "bad" | Select-Object name, team, expired, within7, within30

# Replace-All Drill: dry run for a CA, read the result, then replace them all
$drill = Invoke-RestMethod "$lh/drills" -Method Post -Headers $h -ContentType application/json -Body (@{ ca = "Lab Issuing CA" } | ConvertTo-Json)
(Invoke-RestMethod "$lh/drills/$($drill.id)" -Headers $h).dryRun.items | Select-Object name, status, detail
Invoke-RestMethod "$lh/drills/$($drill.id)/replace" -Method Post -Headers $h

# CA migration: check what the ADCS CA issued against an EJBCA template, move what is ready, then revoke the old ones
$m = Invoke-RestMethod "$lh/ca-migrations" -Method Post -Headers $h -ContentType application/json -Body (@{ fromCa = "Lab ADCS CA"; toTemplateId = 7 } | ConvertTo-Json)
(Invoke-RestMethod "$lh/ca-migrations/$($m.id)" -Headers $h).check.items | Select-Object subject, status, detail
Invoke-RestMethod "$lh/ca-migrations/$($m.id)/move" -Method Post -Headers $h
$n = (Invoke-RestMethod "$lh/ca-migrations/$($m.id)" -Headers $h).awaitingRevoke
Invoke-RestMethod "$lh/ca-migrations/$($m.id)/revoke" -Method Post -Headers $h -ContentType application/json -Body (@{ confirm = $n } | ConvertTo-Json)
# Move in from Keyfactor Command: Look (reads only), then Copy; the password is used for the request and never kept
$kf = @{ from = "keyfactor"; keyfactor = @{ url = "https://keyfactor.example.test/KeyfactorAPI"; authMethod = "basic"; user = "EXAMPLE\lh-move" }; secret = $env:KF_PASSWORD }
(Invoke-RestMethod "$lh/moves/look" -Method Post -Headers $h -ContentType application/json -Body ($kf | ConvertTo-Json -Depth 5)).lines | Select-Object area, name, status, becomes, reason
# Lines are ready, check (a real issue: something lost or not confirmed) or no (stays behind); list only what needs a person:
# (Invoke-RestMethod "$lh/moves/look" ...).lines | Where-Object status -ne "ready"
# Add includeKeys = $true to bring the keys Command holds (needs a key-encryption certificate here and Command's Recover permission;
# the move file's source.keysRecoverable says whether Command showed that permission on a role of the account)
$move = Invoke-RestMethod "$lh/moves" -Method Post -Headers $h -ContentType application/json -Body ($kf | ConvertTo-Json -Depth 5)
Invoke-RestMethod "$lh/moves/$($move.id)/undo" -Method Post -Headers $h -ContentType application/json -Body '{}'

# Key types: what certificates may have, then allow only RSA-3072, RSA-4096 and ECDSA-P256 with RSA-3072 made by default (administrators only)
Invoke-RestMethod "$lh/key-types" -Headers $h
Invoke-RestMethod "$lh/settings/key-types" -Method Put -Headers $h -ContentType application/json `
  -Body '{"allowed":["RSA-3072","RSA-4096","ECDSA-P256"],"default":"RSA-3072"}'

# PFX downloads: keep PFX keys until 30 days after expiry (administrators only), then, as the person who enrolled it, get a PFX again
Invoke-RestMethod "$lh/settings/pfx-downloads" -Method Put -Headers $h -ContentType application/json -Body '{"keep":"after-expiry","for":30,"unit":"days"}'
$p = Invoke-RestMethod "$lh/certificates/$thumbprint/key/download" -Method Post -Headers $h
[IO.File]::WriteAllBytes("$PWD\$($p.fileName)", [Convert]::FromBase64String($p.pfx)); $p.password   # shown once, kept nowhere

# Deprecated cryptography: what is refused, then allow it on one template for old devices (administrators only; a reason is required)
Invoke-RestMethod "$lh/crypto-policy" -Headers $h
Invoke-RestMethod "$lh/settings/crypto-policy" -Method Put -Headers $h -ContentType application/json `
  -Body '{"everywhere":false,"templates":[12],"reason":"Floor 3 printers only do RSA-1024; replace by 2027-03"}'
# ...and back to refusing it everywhere
Invoke-RestMethod "$lh/settings/crypto-policy" -Method Put -Headers $h -ContentType application/json -Body '{"everywhere":false,"templates":[]}'

A CSR or certificate with deprecated cryptography (RSA under 2048 bits, DSA, curves under P-256, SHA-1, MD5 or MD2 signatures) is refused on every route that issues, with HTTP 400 and an error naming what was wrong, unless GET /crypto-policy shows it allowed for that template. See "Deprecated cryptography" in docs/server.md.

A certificate's common name is also one of its DNS names. POST /enroll/check answers with commonNameToAdd: the CN when it is a host name (with a dot) that the CSR does not also list as a DNS name, otherwise null. Lighthouse cannot change a signed CSR, so Vault and DigiCert templates ask the CA to add it and EJBCA and ADCS templates issue the CSR's names as they are; list the CN in the CSR to have it everywhere. A template's allowed domains apply to the CN too. See "Common name as a DNS name" in docs/server.md.

Nobody picks a key type when enrolling. A template's usableKeyTypes (from GET /templates) are the key types it takes once Settings, Application, Key types has narrowed it; a CSR with any other key is refused with 400. madeKeyType is the key to make when the key is made for the person, as the console does for a PFX. Templates take keyType (the key they make; null uses the Settings default) alongside allowedKeyTypes. See "Key types" in docs/server.md.

Facts: send values by fact name in facts for every id in the template's askedFacts (its own facts plus those with everyTemplate); a required one without a value or default answers 400 (required on GET /facts; Enroll tags each Fact Required or Optional). PUT /certificates/{thumbprint}/facts replaces all of a certificate's facts, so a script that fills in one should send the others back too; the rule not fact:<name> lists certificates without it (see the example above). Subject fields: the subject and effectiveSubject on GET /templates (and GET /subject-defaults) are what the console fills in when it builds a CSR in the browser; a CSR you send keeps its own subject. Templates take subject with the same fields; an empty field follows Settings. See "Facts" and "Certificate subject" in docs/server.md.

curl:

curl -H "Authorization: Bearer $LIGHTHOUSE_TOKEN" https://lighthouse.example.test/api/v1/summary

# Renew: a new CSR through a template; owners, tags and facts carry over
jq -n --arg csr "$(cat web01.csr)" '{templateId: 3, csr: $csr}' |
  curl -H "Authorization: Bearer $LIGHTHOUSE_TOKEN" -H "Content-Type: application/json" -d @- \
  "https://lighthouse.example.test/api/v1/certificates/$THUMBPRINT/renew"

What it covers

Holding keys: a template's keepKeyUnit is days, weeks, months, years, indefinitely, never, or null (follow Settings, PFX downloads, which holds nothing until an administrator turns it on, so older templates behave as before), and keepKeyFor is the number (1-3650 days, 1-520 weeks, 1-120 months, 1-10 years; null for indefinitely and never). holdsKey and keyHoldText on GET /templates say what applies; send the sealed key with POST /enroll only when holdsKey is true. The older keepKeyDays still works on requests when keepKeyUnit is not sent, and on answers it is the hold in whole days for days and weeks, otherwise null. A kept key's deleteAfter is null when it is held indefinitely.

Paging: GET /certificates with no new parameters lists every certificate the caller sees, as it always has. With offset or limit (0 to 2000; 100 when only offset is given) it answers one page, and the header X-Total-Count says how many match in all. rule narrows the list with a Spotlight rule (such as expires<=30 and owner:none), sort is daysLeft (default), notAfter, name or issuer, and order is asc or desc; certificates that sort the same are ordered by thumbprint, so pages never repeat or skip one. POST /certificates/query is what the console uses: {rule, search, sort, order, offset, limit, counts, breakdown, horizon, thumbprints, status} answers {all, total, attention, keysKept, offset, limit, certificates, counts, status, hidden}, where counts counts up to 300 other rules over everything the caller sees (a rule that is not understood has n null and an error), breakdown adds issuers and keyTypes (the six commonest and Other) and owners, horizon adds the soonest to expire, and thumbprints every matching thumbprint (up to 10,000). GET /certificates/values?field=domain suggests values for a rule field, most common first.

Managed CAs: a certificate is issued by a managed CA when a template connects to the CA it was read from, or to the CA its issuer names (an EJBCA template's CA, an ADCS template's CA, or DigiCert for a DigiCert template). GET /certificates/{thumbprint} answers managed (true or false), and the rule term managed:no (or managed:yes) finds them in POST /certificates/query, GET /certificates?rule=, Spotlights and the MCP find_certificates tool. managed:no is the built-in Self-signed Spotlight on Certificates: self-signed certificates and those from a CA Lighthouse only found, such as a vendor's own root. Lighthouse cannot revoke them (POST /certificates/{thumbprint}/revoke answers 409 with error), only replace them with POST /certificates/{thumbprint}/renew (or /renew-installed where Installations serve them), so the new one comes from a managed CA. When a template comes to connect to a certificate's CA, the certificate counts as managed from then on.

Status: status on GET /certificates, /certificates.csv and POST /certificates/query is active (in date and not revoked), expired (past its end date and not revoked), revoked or all. Revoked wins, so a revoked certificate is never expired, and the rule term state:expired means the same. Left out, status is all, so a script written before it sees what it always did; the console always sends active unless someone picks another. On the query the status narrows the rule, the search, every count and the breakdown, except a rule (or count) that names a status itself with state:active, state:expired or state:revoked; the answer's status is the one applied (null when the rule named one) and hidden how many more match the rule and search with another status. attention and the horizon never count a revoked certificate. GET /summary counts revoked certificates in revoked and leaves them out of expired, expiringWithin30Days and expiringWithin90Days. The CSV has a Status column. Reports and certificate history are unchanged: they include every status. POST /certificates/served with {lookups: [{file}, {where: "web01.example.com:443"}]} finds the certificate seen at each place, or null.

Teams: GET /owners and GET /teams list teams only. A person who owns certificates themselves (the owner named after their account that enrolling or a personal ACME key makes) is not a team, so it is left out there and from the teams GET /reports offers, though it still shows among a certificate's owners. POST /owners with that person's name is refused with 400, and PUT /owners/{id}/access on it answers 404.

Owners: GET /certificates/{thumbprint} lists owners (given by hand) and ownedThrough, the team Spotlights that make a team its owner, each {teamId, team, spotlightId, spotlight}; both count the same. When neither gives it an owner, defaultOwner is "Admins": the administrators own it by default and it is in the built-in Needs an owner Spotlight (rule owner:none) until someone gives it an owner; otherwise it is null. PUT /certificates/{thumbprint}/owners with {"owners": [4], "note": "they run the site now"} sets the owners given by hand and never changes a Spotlight; note (optional, up to 1000 characters) goes with the new owners' names into the history and the Keeper's Log. To take a certificate away from a team that owns it through a Spotlight, change that Spotlight's rule.

Certificate history: GET /certificates/{thumbprint}/history answers {thumbprint, previous, next, latest, events}. events run newest first, each with when, kind (issued, enrolled, found, seen, installed, removed, renewed, replaced, owners, tags, facts, key, request, pipeline, revoked, expired, expires or other), title, detail, who, thumbprint (another version it links to) and upcoming (true for an expiry still ahead). previous, next and latest are the versions before, after and newest, each with thumbprint, subject, notBefore, notAfter, revoked and how: renewal when Lighthouse renewed it, names when a newer certificate that is not revoked covers all its names. It is built from the inventory and the Keeper's Log entries that name the certificate when asked; links to certificates the caller may not see are left out, and a certificate the caller may not see answers 404.

PFX passwords: the console makes the password of a PFX made in the browser and shows it once; Lighthouse never sees it. GET /pfx-downloads says how long the key is held so the PFX can be downloaded again: keep is off (default), indefinitely, before-expiry or after-expiry, with for and unit (days, weeks, months) for the last two. POST /certificates/{thumbprint}/key/download is for the person who enrolled it (canDownloadAgain on GET /certificates/{thumbprint}/key) and answers {fileName, pfx (base64), password, deleteAfter} with a new password each time, audited as pfx-download. POST /certificates/{thumbprint}/key/recover with only a reason answers the same JSON with a password Lighthouse made; with a password of your own it still answers the PKCS#12 file. If a certificate expires before a before-expiry time, no key is kept and POST /enroll says why in keyNote.

More public CAs (part public-cas, always there within the license): a CA in POST /settings/cas may be "kind": "acme" with settings {"directoryUrl": "https://acme.zerossl.com/v2/DV90", "email": "[email protected]", "eabKeyId": "...", "challenge": "dns-cloudflare", "waitSeconds": 60} and the secrets eabHmacKey and dnsToken beside them (stored, never returned; challenge is dns-cloudflare, dns-manual, http-01 or prevalidated). An ACME CA has no read job, since ACME cannot list what it issued. "kind": "sectigo" takes {"customerUri": "acme", "login": "api-user"} and the SCM password as apiKey; "kind": "godaddy" takes {"customerId": "<GUID>"} and key:secret as apiKey; both get a read job (sectigo-sync, godaddy-sync). GET /settings/cas/acme-directories lists known ACME CAs (name, url, binding, note); GET /settings/cas/{id}/sectigo-profiles?organizationId= lists a Sectigo CA's SSL profiles. Templates take "kind": "acme" with acme (the same fields as the CA, plus authorityName), acmeEabHmacKey and acmeDnsToken; "kind": "sectigo" with sectigo (customerUri, login, organizationId, certType, term, passwordSecret, url, waitSeconds) and sectigoPassword; "kind": "godaddy" with goDaddy (contactEmail, contactFirstName, contactLastName, contactPhone, contactOrganization, productType, period, customerId, apiKeySecret, url, waitSeconds) and goDaddyApiKey. An order the CA has not issued yet answers 409 with what to do; with dns-manual that is the TXT records to add, and sending the same request again finishes the same order. Lighthouse answers the CA's http-01 checks at GET /.well-known/acme-challenge/{token} (no sign-in). See "More public CAs" in docs/server.md.

GET /templates is the list the console's Enroll page picks from: people choose a template there, then send its id as templateId to POST /enroll. An administrator gets every template (including ones that are off); anyone else only the templates opened to them: those whose people name them or a group of theirs (they enroll for themselves, team left out), or whose teams list a team where they hold Enroll certificates for the team itself (they enroll for that team). Enroll certificates given everywhere opens no template, and an API token is named as token:<name>. Templates take "people": ["EXAMPLE\\alice", "group:pki-requesters"] alongside teams; people is shown to administrators only. "peopleUntil": {"EXAMPLE\\alice": "2026-12-31T23:59:59Z"} ends some of them on a date, "teamNamesOnly": true lets a team's request name only what its team Spotlights cover, and "requestsExpireDays": 14 refuses a request that waits for approval longer than that (1 to 90). GET /me returns enrollsFor, the ids of the templates opened to the caller by name or group. See "Who sees which templates" in docs/server.md.

In the body of POST /templates or PUT /templates/{id}: "keepKeyUnit": "years", "keepKeyFor": 2 holds keys for two years, "keepKeyUnit": "indefinitely" until someone destroys them, "keepKeyUnit": "never" not at all, and "keepKeyUnit": null as Settings, PFX downloads says.

Change watch: a scan job's parameters take watchChanges (default true), and each integration under /settings has changes (default true) for whether it gets site change notices. The changes a scan found are in /audit?search=site-change.

Every optional feature (keys above) but ACME is off on a new server, including Network appliances, Cloud vaults, Macs and AI. Routes of their own (/acme-keys, /scep-challenges, /est-credentials, /drills, /ca-migrations, /moves, /outposts, /settings/password-managers, and the ACME, SCEP, EST and Outpost protocols under /acme/, /scep/, /.well-known/est/ and /outpost/v1/) answer 404 with an error naming Settings, Features until an administrator turns them on, so check GET /features first if a script gets an unexpected 404.

To be told when something happens instead of asking, add a webhook (Settings, Integrations, or POST /settings/webhooks) and call it from a Pipeline of the events you want with a call step. Lighthouse then posts signed JSON events to your URL; see Webhooks in docs/server.md for the events, the body and how to check the signature. A webhook takes no events any more (400 when given), GET /settings/webhooks answers calledBy, the Pipelines that call each one, and DELETE /settings/webhooks/{id} answers 409 while a Pipeline calls it.

To keep Lighthouse's server log, audit log and alerts in Splunk, a syslog receiver or another log service, add a log destination (POST /settings/log-destinations with kind splunk, syslog or https); see Log forwarding in docs/server.md for the settings and the event format. For example:

$body = @{ name = "Splunk"; kind = "splunk"; url = "https://splunk.example.test:8088"; token = $env:HEC_TOKEN; index = "pki"; streams = @("audit", "alerts", "app"); minimumLevel = "Warning" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri https://lighthouse.example.test/api/v1/settings/log-destinations -Headers @{ Authorization = "Bearer $env:LIGHTHOUSE_TOKEN" } -ContentType application/json -Body $body

Pipelines decide what happens when certificates are requested, issued, renewed, revoked, expiring, weak or found, change owner or fail to install; see Pipelines in docs/server.md. A request a Pipeline holds answers 202 like any waiting request, with pipeline, waiting and approvals on it; one a Pipeline refuses answers 400 with the Pipeline's message. For example, two Payments approvers and then one from Security for PCI names:

$body = @{ name = "PCI"; event = "certificate.requested"; rule = "domain:pci.example.com";
  steps = @(@{ kind = "approve"; count = 2; team = 4 }, @{ kind = "approve"; count = 1; team = 7 }, @{ kind = "tell"; to = "teams" }) } | ConvertTo-Json -Depth 4
Invoke-RestMethod "$lh/pipelines" -Method Post -Headers $h -ContentType application/json -Body $body
# Which Pipeline would a request for pay.pci.example.com through template 3 take?
Invoke-RestMethod "$lh/pipelines/try" -Method Post -Headers $h -ContentType application/json -Body '{"event":"certificate.requested","names":"pay.pci.example.com","templateId":3}'

Alerts are Pipelines too. Payments hears at 90, 60, 30, 14, 7, 3 and 1 days and then every day, in one list per morning check at 07:00 UTC; its lead is told from 7 days left and ServiceNow gets a ticket from 3:

$body = @{ name = "Payments, escalating"; event = "certificate.expiring"; rule = "team:Payments"; thresholds = "90,60,30,14,7,3,1"; repeatDays = 1; sendHour = 7
  steps = @(@{ kind = "tell"; to = "team"; together = $true }, @{ kind = "tell"; to = "email:[email protected]"; together = $true; fromDays = 7 },
            @{ kind = "tell"; to = "servicenow"; fromDays = 3 }) } | ConvertTo-Json -Depth 4
Invoke-RestMethod "$lh/pipelines" -Method Post -Headers $h -ContentType application/json -Body $body

AI assistants (MCP)

AI assistants such as Claude, Copilot or Cursor can read Lighthouse through the Model Context Protocol at /mcp, beside the API rather than under /api/v1. It is off until an administrator turns on AI under Settings, Features. It takes only an API token (Authorization: Bearer lh_...), never a browser session, and a token sees by MCP exactly what its grant lets it see at /api/v1. Every tool only reads, except suggest_owner (below), which only leaves a suggestion for a person; nothing is changed, enrolled or revoked. Lighthouse itself sends nothing to any AI service: the assistant asks, and whoever runs the assistant decides where its model runs.

Give the token a read-only grant (built-in profile Read-only, limited to teams if you like) and add the server to the assistant. For Claude Code:

claude mcp add --transport http lighthouse https://lighthouse.example.test/mcp \
  --header "Authorization: Bearer $LIGHTHOUSE_TOKEN"

Other assistants take the same address and header in their MCP settings, as a "streamable HTTP" server.

Explain with AI

With the feature ai-explain on and an AI model set up, POST /explain asks the customer's own model to explain one item and answers with its explanation. Lighthouse calls no AI service of its own; see Running the server for what is sent and what is hidden.

Each question is audited as ai-explain. The model only answers: nothing is changed.

Invoke-RestMethod "$lh/explain" -Method Post -Headers $h -ContentType application/json -Body '{"kind":"job","id":"12"}' | Select-Object -ExpandProperty answer

The endpoint is JSON-RPC 2.0 over one POST per message (protocol versions 2025-11-25, 2025-06-18 and 2025-03-26), answered with JSON; GET answers 405 because nothing is pushed back. A request with an Origin header from another site is refused.

Changing the API

Every route under /api/v1 must be described in src/Lighthouse.Server/Dashboard/openapi.json; a test fails otherwise. Add new routes and new optional fields freely. Do not remove a route, rename a field or change what one means: start /api/v2 beside it instead.