Certificates
Use certificates to give a hostname a public TLS certificate. Request a cert, prove you own the name with DNS-01, then attach the issued cert to a Gateway custom domain. Skippr holds the private key; public operations never return it.
Status: Preview. See the API action reference for the full command list.
At a glance
| Fact | Value |
|---|---|
| CLI | skippr certs <operation> |
| Target prefix | CloudCerts. |
| Authentication | Cloud JWT or SigV4 service certs |
| Validation | DNS-01 |
| Private key | Held by the platform; not returned by public operations |
| Contract | API actions |
What you can do
- Request a certificate for one authorized domain and optional additional names.
- Follow an issuance order from
PENDINGtoISSUEDorFAILED. - Describe and list certificates.
- Renew or delete a certificate.
- Attach an issued certificate to a Gateway custom domain.
Before you start
You need skippr login or an operator/workload SigV4 key and permission to request certificates for the hostname. For automatic DNS-01 validation, manage the hostname's zone with DNS. If DNS is external, you must be able to publish the validation record returned by the request.
Site custom domains use a Sites DomainBinding and managed edge TLS. Do not request a gateway certificate for the same Site hostname.
Request, validate, and check a certificate
1. Request the certificate
The same request is CLI, Terraform, CDKTF TypeScript, or CDKTF Python. For provider credentials and the shared cloud provider block, see Terraform and CDKTF. Reuse the same clientToken when retrying the same CLI request. Terraform replacement creates a new certificate.
skippr certs request-certificate --input - <<JSON
{
"domainName": "api.example.com",
"subjectAlternativeNames": ["www.api.example.com"],
"clientToken": "cert-api-example-com-1"
}
JSONresource "cloud_certificate" "api" {
domain_name = "api.example.com"
subject_alternative_names = ["www.api.example.com"]
}import { CloudProvider, CloudCertificate } from "@skippr/provider-cloud";
const cloud = new CloudProvider(this, "cloud", { region: "eu-central-1" });
new CloudCertificate(this, "api", {
domainName: "api.example.com",
subjectAlternativeNames: ["www.api.example.com"],
provider: cloud,
});from skippr_cdktf import CloudProvider, CloudCertificate
cloud = CloudProvider(self, "cloud", region="eu-central-1")
CloudCertificate(
self,
"api",
domain_name="api.example.com",
subject_alternative_names=["www.api.example.com"],
provider=cloud,
)Save certificateId and, when present, orderId. Reuse the same clientToken when retrying the same request.
2. Complete DNS validation
For a Skippr Cloud-managed zone, certs publishes and removes the required DNS-01 record through DNS. No manual record call is required.
When you keep your own DNS, create the Gateway domain name first and pass the returned acmeDelegationCname ({token}.validation.skippr.io) on RequestCertificate. Publish _acme-challenge.{hostname} as a CNAME to that target. Skippr writes the challenge TXT at the CNAME target. Leave the CNAME in place for renewal. Do not put DNS provider credentials in the certificate request.
3. Read order status
skippr certs get-order --order-id '<orderId>'Read detail when the order reaches FAILED. When status is ISSUED, use DescribeCertificate to read the validity window and attach the certificateId to a supported gateway DomainName.
Understand certificates and orders
| Concept | Meaning |
|---|---|
| Certificate | Certificate metadata and an issued public chain |
| Order | One issuance or renewal attempt |
| SAN | Another hostname covered by the same certificate |
| DNS-01 | TXT-record proof that you control a hostname |
certificateId | Opaque identifier used by describe, renew, delete, and gateway domain operations |
orderId | Opaque identifier used by GetOrder |
Order and certificate status values are:
| Status | Meaning |
|---|---|
PENDING | The request was accepted |
CHALLENGE_PLANNED | Validation record details are ready |
CHALLENGE_PUBLISHED | Managed DNS published the challenge |
VALIDATING | The issuer is checking DNS |
ISSUED | The certificate is ready |
FAILED | Issuance ended with an error; inspect detail |
RENEWING | A renewal order is running |
REVOKED, EXPIRED, DELETED | The certificate cannot be used for new TLS attachment |
Manage the lifecycle
| Task | Supported operations |
|---|---|
| Request and track issuance | RequestCertificate, GetOrder |
| Read certificates | DescribeCertificate, ListCertificates |
| Renew | RenewCertificate |
| Remove | DeleteCertificate |
cloud_certificate is the Terraform resource for request, read, list, and delete lifecycle. CDKTF TypeScript and Python expose bindings generated from the same resource contract.
Limits and errors
- Certificate names must be within your authorized domain scope.
- Subject alternative name count and concurrent orders are bounded by issuer and Preview policy; no numeric public quota is currently guaranteed.
- Issuer rate limits apply. Prefer idempotent retries instead of creating a new request for the same names.
- Private keys are never returned by request, describe, list, or order operations.
- 400: the domain, SAN, order, or request shape is invalid.
- 401: authentication is missing or invalid.
- 403: the caller is not authorized for one or more requested names.
- 404: the certificate or order does not exist.
- 409: the request conflicts with the current certificate or order state.
- 500: certificate metadata or protected material could not be persisted.
DNS-01 or issuer failures return 400 with an invalid-request detail. Before retrying, fix the validation record when required; reuse the same clientToken for the same certificate request.