ACME Endpoints
ACME Endpoints
All ACME endpoints are under the root path and require JWS-signed requests (RFC 8555 §6) except the directory and nonce endpoints.
Base URL
https://<upki-ra-host>:8000
Directory
GET /acme/directory
Returns the ACME directory object. Configure your ACME client's caServer to this URL.
Response:
{
"newNonce": "https://upki-ra:8000/acme/new-nonce",
"newAccount": "https://upki-ra:8000/acme/new-account",
"newOrder": "https://upki-ra:8000/acme/new-order",
"revokeCert": "https://upki-ra:8000/acme/revoke-cert",
"keyChange": "https://upki-ra:8000/acme/key-change",
"meta": {
"termsOfService": "https://upki-ra:8000/acme/terms",
"caaIdentities": []
}
}
Nonce
| Method | Path | Status |
|---|---|---|
GET | /acme/new-nonce | 204 No Content |
HEAD | /acme/new-nonce | 200 OK |
Returns a fresh nonce in the Replay-Nonce response header. Every JWS-signed request must include a fresh nonce.
Accounts
| Method | Path | Description |
|---|---|---|
POST | /acme/new-account | Create or locate an account |
POST | /acme/account/{id} | Update or deactivate an account |
POST | /acme/key-change | Rotate the account key |
Create account
POST /acme/new-account
Request body (JWS-signed, protected header contains jwk):
{
"termsOfServiceAgreed": true,
"contact": ["mailto:admin@example.com"]
}
Response: 201 Created with account object and Location header.
Orders
| Method | Path | Description |
|---|---|---|
POST | /acme/new-order | Create a new order |
GET | /acme/order/{id} | Get order status |
POST | /acme/order/{id} | Update order (bump status) |
POST | /acme/order/{id}/finalize | Submit CSR, trigger certificate issuance |
Create order
POST /acme/new-order
Request body:
{
"identifiers": [{ "type": "dns", "value": "app.example.internal" }]
}
Response: 201 Created with order object including authorizations and finalize URLs.
Authorizations
| Method | Path | Description |
|---|---|---|
GET | /acme/authz/{id} | Get authorization status and challenges |
POST | /acme/authz/{id} | Deactivate an authorization |
Challenges
| Method | Path | Description |
|---|---|---|
POST | /acme/challenge/{auth_id}/http-01 | Trigger HTTP-01 challenge validation |
POST | /acme/challenge/{auth_id}/dns-01 | Trigger DNS-01 challenge validation |
POST | /acme/challenge/{auth_id}/tls-alpn-01 | Trigger TLS-ALPN-01 challenge validation |
GET | /.well-known/acme-challenge/{token} | Serve HTTP-01 challenge token |
Certificate issuance
POST /acme/order/{id}/finalize
Request body (JWS-signed):
{
"csr": "<base64url-encoded-DER-CSR>"
}
The RA forwards the CSR to the CA over ZMQ, receives the signed certificate, and transitions the order to valid status.
Certificate revocation
POST /acme/revoke-cert
Request body (JWS-signed with account key or certificate key):
{
"certificate": "<base64url-encoded-DER-cert>",
"reason": 1
}
RFC 5280 reason codes: 0 = unspecified, 1 = keyCompromise, 3 = affiliationChanged, 4 = superseded, 5 = cessationOfOperation.
Public REST endpoints (no auth)
These endpoints do not require ACME JWS signing.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/public/health | Health check |
GET | /api/v1/public/ca | Download CA certificate (PEM) |
GET | /api/v1/public/crl | Download current CRL |
GET | /api/v1/public/profiles | List available certificate profiles |
GET | /api/v1/public/profiles/{name} | Get profile details |
POST | /api/v1/public/certify | Request a node certificate (seed-based) |
GET | /api/v1/public/certs | List issued certificates |
GET | /api/v1/public/certs/{cn} | Get certificate by CN |
GET | /api/v1/public/magic/{profile} | Auto-generate certificate (magic mode) |
POST | /api/v1/public/ocsp | OCSP status check |
Private REST endpoints (mTLS required)
All endpoints under /api/v1/private/ require a valid mTLS client certificate.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/private/nodes | List all registered nodes |
POST | /api/v1/private/nodes | Register a new node |
DELETE | /api/v1/private/nodes/{cn} | Delete a node |
GET | /api/v1/private/admins | List admin nodes |
POST | /api/v1/private/admins | Add admin node |
DELETE | /api/v1/private/admins/{dn} | Remove admin node |
POST | /api/v1/private/crl/generate | Trigger CRL regeneration |
GET | /api/v1/private/config | Get RA configuration |
GET | /api/v1/private/options | Get CA options |