> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KeylessSSL API reference

> Implemented KeylessSSL HTTP routes, authentication requirements, scopes, and integration notes.

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

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.