Skip to main content

​
KeylessSSL developer documentation

KeylessSSL exposes an HTTP API at https://api.keylessssl.dev. The portal uses the same API through a typed fetch adapter.

​
Integration sequence

  1. Sign in to the portal and create an API key with only the scopes your integration needs. Save the returned secret when it is displayed; creation and rotation are the only handlers that return it.
  2. Create a base domain with POST /v1/domains.
  3. Read GET /v1/domains/{domainId}/delegation-record and publish both its ownership TXT and delegation CNAME records.
  4. Call POST /v1/domains/{domainId}/verify-delegation. Verification is tenant-bound by the unique ownership TXT value and an atomic apex claim.
  5. After verification, call POST /v1/domains/{domainId}/certificates/issue.
  6. Poll POST /v1/certificates/{certificateId}/sync when the provider reports a pending certificate, or subscribe a webhook to current emitted events.

Quickstart

Orientation for integrators and contributors: architecture, API surface, and local setup.

Architecture overview

Review entry points, storage, auth, runtime configuration, and deployment.

API reference

See the implemented routes, authentication rules, scopes, and a curl request.

​
Authentication choices

The production portal uses an Auth0 Authorization Code flow with PKCE and a backend code exchange. The API returns a KeylessSSL session token, which the portal sends as a bearer token and also stores in an HTTP-only session cookie. Programmatic callers use a KeylessSSL API key in the Authorization: Bearer ... header. API keys are organization-scoped and carry one or more of these implemented scopes:
  • domains:read
  • domains:write
  • certs:read
  • certs:issue
  • webhooks:write
  • audit:read
API keys do not manage organization settings. Interactive users are additionally constrained by their owner, admin, operator, or read-only role.

​
Webhook integration

The backend currently emits domain.verified, cert.requested, and cert.issued. The test route sends webhook.test to one registered endpoint. Deliveries are JSON POST requests with event, timestamp, and HMAC signature headers; failed non-test deliveries are stored and retried by the API worker.