KeylessSSL API reference

Base URL: https://api.keylessssl.dev

Authentication

All /v1 routes after the authentication handlers require a bearer token or the dcvaas_session cookie. Programmatic requests normally send an API key:

curl -sS -X POST "https://api.keylessssl.dev/v1/domains/query" \
  -H "Authorization: Bearer ${KEYLESSSSL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

The example requires an active key with domains:read. API keys begin with the prefix recognized by the server, are stored as hashes, may expire, and can be revoked. The API updates a key’s last-used timestamp after successful authentication.

Service and authentication routes

Method	Path	Access and behavior
GET	`/healthz`	Public process health response.
GET	`/readyz`	Public readiness check that queries PostgreSQL.
POST	`/v1/auth/signup`	Public local-password signup when local auth and public signup are enabled.
POST	`/v1/auth/login`	Public local-password login when local auth is enabled.
POST	`/auth/oidc/callback`	Public Auth0 BFF code exchange used by the portal.
GET, POST	`/v1/auth/verify-email`	Public local-email verification using a token.
POST	`/v1/auth/logout`	Clears the KeylessSSL session cookie.
GET	`/v1/auth/session`	Authenticated user, organization, and email-verification state.

The source also implements a secret-gated end-to-end test login. It is an internal QA route, not a consumer integration endpoint, and is intentionally not documented here.

Account, organization, and team routes

Method	Path	Access and behavior
GET, PATCH	`/v1/account/profile`	Read or update the signed-in user’s profile. API keys cannot update it.
GET	`/v1/orgs`	List organizations available to the authenticated user.
GET	`/v1/orgs/current`	Read the current organization.
POST	`/v1/orgs/current`	Switch a signed-in user to another organization membership.
PATCH	`/v1/orgs/current`	Rename the current organization; owner or admin.
GET	`/v1/team/members`	List members; any implemented team role.
POST	`/v1/team/invite`	Add or update an invited membership; owner or admin.
PATCH	`/v1/team/members/{memberId}`	Change a member role; owner or admin.
DELETE	`/v1/team/members/{memberId}`	Remove a member; owner or admin.

Domain routes

Method	Path	Required scope or role
POST	`/v1/domains/query`	`domains:read` for API keys.
GET	`/v1/domains/{domainId}`	`domains:read` for API keys.
POST	`/v1/domains`	`domains:write`; interactive owner, admin, or operator; verified email for users.
POST	`/v1/domains/bulk`	`domains:write`; same write role and verification rule; accepts at most 500 apex values.
PATCH	`/v1/domains/{domainId}`	`domains:write`; updates tags and notes.
DELETE	`/v1/domains/{domainId}`	`domains:write`; also releases that organization’s apex claim.
GET	`/v1/domains/{domainId}/delegation-record`	`domains:read`; returns the CNAME and tenant-specific ownership TXT when present.
POST	`/v1/domains/{domainId}/verify-delegation`	`domains:write`; performs live ownership and delegation DNS checks.
POST	`/v1/domains/{domainId}/recheck`	`domains:write`; repeats verification and updates operational state.

Certificate routes

Method	Path	Required scope or behavior
POST	`/v1/domains/{domainId}/certificates/issue`	`certs:issue`; verified domain and verified user for interactive sessions. Accepts optional `wildcard`.
POST	`/v1/domains/{domainId}/certificates/query`	`certs:read`; lists certificates for one organization-owned domain.
GET	`/v1/certificates/{certificateId}`	`certs:read`.
POST	`/v1/certificates/{certificateId}/sync`	`certs:issue`; refreshes Cloudflare-backed certificate and domain state.
GET	`/v1/certificates/{certificateId}/bundle`	`certs:read`; returns a bundle only when stored. Cloudflare edge-managed records normally have no exposed bundle.

API-key and webhook routes

Method	Path	Access and behavior
GET	`/v1/api-keys`	Interactive owner, admin, operator, or read-only user.
POST	`/v1/api-keys`	Interactive owner, admin, or operator with verified email. Returns the new secret.
POST	`/v1/api-keys/{apiKeyId}/rotate`	Interactive owner, admin, or operator. Replaces and returns the secret.
POST	`/v1/api-keys/{apiKeyId}/revoke`	Interactive owner, admin, or operator.
GET	`/v1/webhooks`	`webhooks:write`.
POST	`/v1/webhooks`	`webhooks:write`; production URLs must use HTTPS and resolve to a public destination. Returns the signing secret.
PATCH	`/v1/webhooks/{webhookId}`	`webhooks:write`; updates URL, events, or active/disabled state.
DELETE	`/v1/webhooks/{webhookId}`	`webhooks:write`.
POST	`/v1/webhooks/{webhookId}/rotate-secret`	`webhooks:write`; replaces and returns the signing secret.
POST	`/v1/webhooks/{webhookId}/test`	`webhooks:write`; sends one signed `webhook.test` delivery without retrying it.

Current backend emission sites send domain.verified, cert.requested, and cert.issued. Webhook requests include x-keylessssl-event, x-keylessssl-timestamp, and x-keylessssl-signature headers. The JSON body contains the event name, event data, delivery time, and delivery ID.

Audit, usage, client, and verification-link routes

Method	Path	Access and behavior
POST	`/v1/audit/query`	`audit:read`; filters by query text and action.
GET	`/v1/usage`	Returns current organization plan and domain, seat, and rate-limit usage.
POST	`/v1/clients/query`	Lists organization clients.
GET	`/v1/clients/{clientId}`	Reads an organization client and domain counts.
POST	`/v1/clients`	Interactive owner, admin, or operator.
PATCH	`/v1/clients/{clientId}`	Interactive owner, admin, or operator.
DELETE	`/v1/clients/{clientId}`	Interactive owner or admin.
POST	`/v1/verification-links/query`	Lists organization verification links.
POST	`/v1/verification-links`	Interactive owner, admin, or operator.
POST	`/v1/verification-links/{linkId}/remind`	Interactive owner, admin, or operator; marks the link sent and records reminder time.
POST	`/v1/site-scan/https`	Checks HTTPS for a supplied URL or domain.

The client and verification-link handlers are implemented in the API adapter, but the current KeylessSSL portal navigation does not expose dedicated client or verification-link screens.

Billing and account-security routes

Method	Path	Access and behavior
GET	`/v1/billing/plans`	Authenticated plan catalog.
GET	`/v1/billing`	Authenticated current-organization billing state.
POST	`/v1/billing/checkout`	Owner or admin; starts Pro checkout or provisions the free Hacker plan.
GET	`/v1/account/security/methods`	Signed-in user; lists Auth0 authentication methods.
GET	`/v1/account/security/factors`	Signed-in user; lists available Auth0 factors.
POST	`/v1/account/security/passkey/begin`	Signed-in user; starts passkey enrollment.
POST	`/v1/account/security/passkey/complete`	Signed-in user; completes passkey enrollment.
POST	`/v1/account/security/totp/begin`	Signed-in user; starts authenticator-app enrollment.
POST	`/v1/account/security/totp/verify`	Signed-in user; verifies the one-time code.
DELETE	`/v1/account/security/methods/{id}`	Signed-in user; removes an enrolled method.

Stripe and transactional-email provider callback routes exist outside the consumer API. They validate provider signatures and are intentionally omitted as integration endpoints.

Errors and request tracing

The API assigns or preserves an x-request-id value and returns it in the response header. Application errors use JSON fields for code, message, requestId, and optional details. Unknown routes are handled as errors rather than falling through to an unrelated endpoint.

Start here

Documentation hubs

Legal

Shared legal

KeylessSSL API reference

KeylessSSL API reference

Authentication

Service and authentication routes

Account, organization, and team routes

Domain routes

Certificate routes

API-key and webhook routes

Audit, usage, client, and verification-link routes

Billing and account-security routes

Errors and request tracing

​KeylessSSL API reference

​Authentication

​Service and authentication routes

​Account, organization, and team routes

​Domain routes

​Certificate routes

​API-key and webhook routes

​Audit, usage, client, and verification-link routes

​Billing and account-security routes

​Errors and request tracing

KeylessSSL API reference

Authentication

Service and authentication routes

Account, organization, and team routes

Domain routes

Certificate routes

API-key and webhook routes

Audit, usage, client, and verification-link routes

Billing and account-security routes

Errors and request tracing