CA Accounts & Gateways

Generated from core/api/router.go. Edit the router, not this file.

Method	Path	Who can call it
GET	/api/v1/ca-accounts	Any authenticated user
POST	/api/v1/ca-accounts	Operator, admin
DELETE	/api/v1/ca-accounts/:id	Admin
POST	/api/v1/ca-accounts/:id/health	Operator, admin
PUT	/api/v1/ca-accounts/:id/rate-limit	Operator, admin
GET	/api/v1/gateways	Any authenticated user

Registering

{
  "name": "letsencrypt-prod",
  "provider_type": "acme",
  "gateway_addr": "acme-gateway:9092",
  "server_name": "acme-gateway",
  "config": {
    "directory_url": "letsencrypt",
    "email": "ops@example.com",
    "challenge": "dns-01",
    "dns_provider": "cloudflare",
    "dns_config": {"api_token": "..."}
  },
  "is_default": false
}

The core connects over mTLS, calls the gateway's ValidateConfig, and stores nothing if the gateway rejects it — a 400 comes back listing what is wrong. Warnings do not block and are returned alongside the created account.

config is sealed with AES-256-GCM before storage and decrypted only to populate a single outbound gRPC call. It is not readable back through the API.

server_name overrides the name expected in the gateway's TLS certificate; omit it to derive from the host part of gateway_addr.

Endpoint detail

GET /api/v1/ca-accounts

Who can call it	Any authenticated user
Handler	caAccHandler.List
Display token	Readable by an unattended screen

Responses

Status	Body
200	An object with data (CAAccount[]), total
500	{ "error": … }

Example request

curl -X GET 'https://certpilot.example.com/api/v1/ca-accounts' \
  -H 'Authorization: Bearer <token>'

POST /api/v1/ca-accounts

Who can call it	Operator, admin
Handler	caAccHandler.Create
Display token	Refused — not a viewer-safe GET

Request body

CreateCAAccountInput is the payload for registering a CA account.

Field	Type		Description
name	string	required
provider_type	string	required
gateway_addr	string	required
server_name	string		ServerName overrides the name expected in the gateway's TLS certificate.
config	object		Config carries provider-specific settings — directory URLs, API tokens, DNS credentials. It is validated by the gateway and then sealed before it reaches the database; it is never returned by any endpoint.
is_default	boolean
renewal_rate_limit	integer		RenewalRateLimit is how many certificates this account may successfully renew inside the window. Zero, the default, means unlimited.
renewal_rate_window_hours	integer		RenewalRateWindowHours is the rolling window, defaulting to a week.

Responses

Status	Body
201	An object with data (CAAccount), issuers, warnings (string[])
400	An object with validation_error, warnings · the gateway rejected this configuration
500	{ "error": … }
502	{ "error": … }

Example request

curl -X POST 'https://certpilot.example.com/api/v1/ca-accounts' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "<name>",
  "provider_type": "<provider_type>",
  "gateway_addr": "<gateway_addr>",
  "server_name": "<server_name>",
  "config": {}
}'

DELETE /api/v1/ca-accounts/:id

Who can call it	Admin
Handler	caAccHandler.Delete
Display token	Refused — not a viewer-safe GET

Parameters

Name	In		Default
id	path	required

Responses

Status	Body
200	An object with message (string)
500	{ "error": … }

Example request

curl -X DELETE 'https://certpilot.example.com/api/v1/ca-accounts/<id>' \
  -H 'Authorization: Bearer <token>'

POST /api/v1/ca-accounts/:id/health

Who can call it	Operator, admin
Handler	caAccHandler.HealthCheck
Display token	Refused — not a viewer-safe GET

Parameters

Name	In		Default
id	path	required

Responses

Status	Body
200	An object with latency_ms, message, status
404	{ "error": … }
503	{ "error": … }

Example request

curl -X POST 'https://certpilot.example.com/api/v1/ca-accounts/<id>/health' \
  -H 'Authorization: Bearer <token>'

PUT /api/v1/ca-accounts/:id/rate-limit

Who can call it	Operator, admin
Handler	caAccHandler.SetRateLimit
Display token	Refused — not a viewer-safe GET

Narrow on purpose: the only field on a CA account that can change without re-validating the configuration through the gateway.

Parameters

Name	In		Default
id	path	required

Request body

RateLimitInput sets how hard this account may be renewed against.

Field	Type		Description
renewal_rate_limit	integer	required	Limit is certificates per window. Zero means unlimited.
renewal_rate_window_hours	integer		WindowHours defaults to a week when not given.

Responses

Status	Body
200	An object with data (CAAccount), message
400	{ "error": … } · renewal_rate_limit cannot be negative; use 0 for unlimited · renewal_rate_window_hours cannot be negative
404	{ "error": … }
500	{ "error": … }

Example request

curl -X PUT 'https://certpilot.example.com/api/v1/ca-accounts/<id>/rate-limit' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "renewal_rate_limit": 0,
  "renewal_rate_window_hours": 0
}'

GET /api/v1/gateways

Who can call it	Any authenticated user
Handler	caAccHandler.ListGateways
Display token	Readable by an unattended screen

Responses

Status	Body
200	An object with data, total

Example request

curl -X GET 'https://certpilot.example.com/api/v1/gateways' \
  -H 'Authorization: Bearer <token>'