Create certificate
curl --request POST \
--url https://certificate.{region}.basaltic.sh/v1/certificates \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "prod-frontend",
"domains": [
"example.com",
"www.example.com",
"api.example.com"
],
"key_algorithm": "ecdsa-p256",
"source": "acme",
"certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n",
"chain_pem": "-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n",
"private_key_pem": "-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEG...\n-----END PRIVATE KEY-----\n",
"tags": {
"environment": "production",
"team": "backend"
}
}
'import requests
url = "https://certificate.{region}.basaltic.sh/v1/certificates"
payload = {
"name": "prod-frontend",
"domains": ["example.com", "www.example.com", "api.example.com"],
"key_algorithm": "ecdsa-p256",
"source": "acme",
"certificate_pem": "-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAaH...
-----END CERTIFICATE-----
",
"chain_pem": "-----BEGIN CERTIFICATE-----
MIIEFzCCAv+gAwIBAgIEBb2...
-----END CERTIFICATE-----
",
"private_key_pem": "-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEG...
-----END PRIVATE KEY-----
",
"tags": {
"environment": "production",
"team": "backend"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'prod-frontend',
domains: ['example.com', 'www.example.com', 'api.example.com'],
key_algorithm: 'ecdsa-p256',
source: 'acme',
certificate_pem: '-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n',
chain_pem: '-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n',
private_key_pem: '-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEG...\n-----END PRIVATE KEY-----\n',
tags: {environment: 'production', team: 'backend'}
})
};
fetch('https://certificate.{region}.basaltic.sh/v1/certificates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://certificate.{region}.basaltic.sh/v1/certificates",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'prod-frontend',
'domains' => [
'example.com',
'www.example.com',
'api.example.com'
],
'key_algorithm' => 'ecdsa-p256',
'source' => 'acme',
'certificate_pem' => '-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAaH...
-----END CERTIFICATE-----
',
'chain_pem' => '-----BEGIN CERTIFICATE-----
MIIEFzCCAv+gAwIBAgIEBb2...
-----END CERTIFICATE-----
',
'private_key_pem' => '-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEG...
-----END PRIVATE KEY-----
',
'tags' => [
'environment' => 'production',
'team' => 'backend'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://certificate.{region}.basaltic.sh/v1/certificates"
payload := strings.NewReader("{\n \"name\": \"prod-frontend\",\n \"domains\": [\n \"example.com\",\n \"www.example.com\",\n \"api.example.com\"\n ],\n \"key_algorithm\": \"ecdsa-p256\",\n \"source\": \"acme\",\n \"certificate_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIDdzCCAl+gAwIBAgIEAaH...\\n-----END CERTIFICATE-----\\n\",\n \"chain_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIEFzCCAv+gAwIBAgIEBb2...\\n-----END CERTIFICATE-----\\n\",\n \"private_key_pem\": \"-----BEGIN PRIVATE KEY-----\\nMIGHAgEAMBMGByqGSM49AgEG...\\n-----END PRIVATE KEY-----\\n\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://certificate.{region}.basaltic.sh/v1/certificates")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"prod-frontend\",\n \"domains\": [\n \"example.com\",\n \"www.example.com\",\n \"api.example.com\"\n ],\n \"key_algorithm\": \"ecdsa-p256\",\n \"source\": \"acme\",\n \"certificate_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIDdzCCAl+gAwIBAgIEAaH...\\n-----END CERTIFICATE-----\\n\",\n \"chain_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIEFzCCAv+gAwIBAgIEBb2...\\n-----END CERTIFICATE-----\\n\",\n \"private_key_pem\": \"-----BEGIN PRIVATE KEY-----\\nMIGHAgEAMBMGByqGSM49AgEG...\\n-----END PRIVATE KEY-----\\n\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://certificate.{region}.basaltic.sh/v1/certificates")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"prod-frontend\",\n \"domains\": [\n \"example.com\",\n \"www.example.com\",\n \"api.example.com\"\n ],\n \"key_algorithm\": \"ecdsa-p256\",\n \"source\": \"acme\",\n \"certificate_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIDdzCCAl+gAwIBAgIEAaH...\\n-----END CERTIFICATE-----\\n\",\n \"chain_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIEFzCCAv+gAwIBAgIEBb2...\\n-----END CERTIFICATE-----\\n\",\n \"private_key_pem\": \"-----BEGIN PRIVATE KEY-----\\nMIGHAgEAMBMGByqGSM49AgEG...\\n-----END PRIVATE KEY-----\\n\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}"
response = http.request(request)
puts response.read_body{
"certificate": {
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"crn": "crn:certificate::my-account:certificate/prod-frontend",
"name": "prod-frontend",
"domains": [
"example.com",
"www.example.com",
"api.example.com"
],
"status": "active",
"source": "acme",
"key_algorithm": "ecdsa-p256",
"challenges": [
{
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"domain": "*.example.com",
"cname_record_name": "_acme-challenge.example.com.",
"expected_cname": "a1b2c3d4e5f6g7h8.acme.basaltic.cloud.",
"our_dns": true,
"verified": true,
"verified_at": "2026-01-15T09:28:00Z"
}
],
"certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n",
"chain_pem": "-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n",
"fingerprint": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"issued_at": "2026-01-15T09:30:00Z",
"expires_at": "2026-04-15T09:30:00Z",
"tags": {
"environment": "production",
"team": "backend"
}
}
}{
"certificate": {
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"crn": "crn:certificate::my-account:certificate/prod-frontend",
"name": "prod-frontend",
"domains": [
"example.com",
"www.example.com",
"api.example.com"
],
"status": "active",
"source": "acme",
"key_algorithm": "ecdsa-p256",
"challenges": [
{
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"domain": "*.example.com",
"cname_record_name": "_acme-challenge.example.com.",
"expected_cname": "a1b2c3d4e5f6g7h8.acme.basaltic.cloud.",
"our_dns": true,
"verified": true,
"verified_at": "2026-01-15T09:28:00Z"
}
],
"certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n",
"chain_pem": "-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n",
"fingerprint": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"issued_at": "2026-01-15T09:30:00Z",
"expires_at": "2026-04-15T09:30:00Z",
"tags": {
"environment": "production",
"team": "backend"
}
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "ACCESS_DENIED",
"message": "You don't have permission to perform this action",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"params": {
"instances": 2,
"pools": 0
}
}
}{
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "This Idempotency-Key was already used with a different request payload",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "INTERNAL_ERROR",
"message": "An internal error occurred",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}Certificates
Create certificate
Create a new certificate. Defaults to ACME issuance; set
source=uploaded to store customer-supplied PEM material
directly.
For ACME source: returns 202 with status pending_dns and one
challenges entry per normalized domain, including cname_record_name,
expected_cname and our_dns. Use these fields directly from the
create response to configure DNS. Challenge planning completes before
creation is accepted; a planning failure rejects the request without
saving a certificate or partial challenge plan.
When our_dns=true, the CNAME is created automatically during
asynchronous issuance. Otherwise, publish cname_record_name CNAME expected_cname at your DNS provider. Wildcards validate at their parent
name; an apex and its wildcard share the same CNAME. Poll
GET /v1/certificates/ for progress. The certificate
becomes active once every challenge verifies and issuance completes.
For uploaded source: returns 201 with status active.
POST
/
v1
/
certificates
Create certificate
curl --request POST \
--url https://certificate.{region}.basaltic.sh/v1/certificates \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "prod-frontend",
"domains": [
"example.com",
"www.example.com",
"api.example.com"
],
"key_algorithm": "ecdsa-p256",
"source": "acme",
"certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n",
"chain_pem": "-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n",
"private_key_pem": "-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEG...\n-----END PRIVATE KEY-----\n",
"tags": {
"environment": "production",
"team": "backend"
}
}
'import requests
url = "https://certificate.{region}.basaltic.sh/v1/certificates"
payload = {
"name": "prod-frontend",
"domains": ["example.com", "www.example.com", "api.example.com"],
"key_algorithm": "ecdsa-p256",
"source": "acme",
"certificate_pem": "-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAaH...
-----END CERTIFICATE-----
",
"chain_pem": "-----BEGIN CERTIFICATE-----
MIIEFzCCAv+gAwIBAgIEBb2...
-----END CERTIFICATE-----
",
"private_key_pem": "-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEG...
-----END PRIVATE KEY-----
",
"tags": {
"environment": "production",
"team": "backend"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'prod-frontend',
domains: ['example.com', 'www.example.com', 'api.example.com'],
key_algorithm: 'ecdsa-p256',
source: 'acme',
certificate_pem: '-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n',
chain_pem: '-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n',
private_key_pem: '-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEG...\n-----END PRIVATE KEY-----\n',
tags: {environment: 'production', team: 'backend'}
})
};
fetch('https://certificate.{region}.basaltic.sh/v1/certificates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://certificate.{region}.basaltic.sh/v1/certificates",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'prod-frontend',
'domains' => [
'example.com',
'www.example.com',
'api.example.com'
],
'key_algorithm' => 'ecdsa-p256',
'source' => 'acme',
'certificate_pem' => '-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAaH...
-----END CERTIFICATE-----
',
'chain_pem' => '-----BEGIN CERTIFICATE-----
MIIEFzCCAv+gAwIBAgIEBb2...
-----END CERTIFICATE-----
',
'private_key_pem' => '-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEG...
-----END PRIVATE KEY-----
',
'tags' => [
'environment' => 'production',
'team' => 'backend'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://certificate.{region}.basaltic.sh/v1/certificates"
payload := strings.NewReader("{\n \"name\": \"prod-frontend\",\n \"domains\": [\n \"example.com\",\n \"www.example.com\",\n \"api.example.com\"\n ],\n \"key_algorithm\": \"ecdsa-p256\",\n \"source\": \"acme\",\n \"certificate_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIDdzCCAl+gAwIBAgIEAaH...\\n-----END CERTIFICATE-----\\n\",\n \"chain_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIEFzCCAv+gAwIBAgIEBb2...\\n-----END CERTIFICATE-----\\n\",\n \"private_key_pem\": \"-----BEGIN PRIVATE KEY-----\\nMIGHAgEAMBMGByqGSM49AgEG...\\n-----END PRIVATE KEY-----\\n\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://certificate.{region}.basaltic.sh/v1/certificates")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"prod-frontend\",\n \"domains\": [\n \"example.com\",\n \"www.example.com\",\n \"api.example.com\"\n ],\n \"key_algorithm\": \"ecdsa-p256\",\n \"source\": \"acme\",\n \"certificate_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIDdzCCAl+gAwIBAgIEAaH...\\n-----END CERTIFICATE-----\\n\",\n \"chain_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIEFzCCAv+gAwIBAgIEBb2...\\n-----END CERTIFICATE-----\\n\",\n \"private_key_pem\": \"-----BEGIN PRIVATE KEY-----\\nMIGHAgEAMBMGByqGSM49AgEG...\\n-----END PRIVATE KEY-----\\n\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://certificate.{region}.basaltic.sh/v1/certificates")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"prod-frontend\",\n \"domains\": [\n \"example.com\",\n \"www.example.com\",\n \"api.example.com\"\n ],\n \"key_algorithm\": \"ecdsa-p256\",\n \"source\": \"acme\",\n \"certificate_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIDdzCCAl+gAwIBAgIEAaH...\\n-----END CERTIFICATE-----\\n\",\n \"chain_pem\": \"-----BEGIN CERTIFICATE-----\\nMIIEFzCCAv+gAwIBAgIEBb2...\\n-----END CERTIFICATE-----\\n\",\n \"private_key_pem\": \"-----BEGIN PRIVATE KEY-----\\nMIGHAgEAMBMGByqGSM49AgEG...\\n-----END PRIVATE KEY-----\\n\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}"
response = http.request(request)
puts response.read_body{
"certificate": {
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"crn": "crn:certificate::my-account:certificate/prod-frontend",
"name": "prod-frontend",
"domains": [
"example.com",
"www.example.com",
"api.example.com"
],
"status": "active",
"source": "acme",
"key_algorithm": "ecdsa-p256",
"challenges": [
{
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"domain": "*.example.com",
"cname_record_name": "_acme-challenge.example.com.",
"expected_cname": "a1b2c3d4e5f6g7h8.acme.basaltic.cloud.",
"our_dns": true,
"verified": true,
"verified_at": "2026-01-15T09:28:00Z"
}
],
"certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n",
"chain_pem": "-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n",
"fingerprint": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"issued_at": "2026-01-15T09:30:00Z",
"expires_at": "2026-04-15T09:30:00Z",
"tags": {
"environment": "production",
"team": "backend"
}
}
}{
"certificate": {
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"crn": "crn:certificate::my-account:certificate/prod-frontend",
"name": "prod-frontend",
"domains": [
"example.com",
"www.example.com",
"api.example.com"
],
"status": "active",
"source": "acme",
"key_algorithm": "ecdsa-p256",
"challenges": [
{
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"domain": "*.example.com",
"cname_record_name": "_acme-challenge.example.com.",
"expected_cname": "a1b2c3d4e5f6g7h8.acme.basaltic.cloud.",
"our_dns": true,
"verified": true,
"verified_at": "2026-01-15T09:28:00Z"
}
],
"certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n",
"chain_pem": "-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n",
"fingerprint": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"issued_at": "2026-01-15T09:30:00Z",
"expires_at": "2026-04-15T09:30:00Z",
"tags": {
"environment": "production",
"team": "backend"
}
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "ACCESS_DENIED",
"message": "You don't have permission to perform this action",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"params": {
"instances": 2,
"pools": 0
}
}
}{
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "This Idempotency-Key was already used with a different request payload",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "INTERNAL_ERROR",
"message": "An internal error occurred",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}Requires the IAM action
certificate:CreateCertificate. See CERTIFICATE permissions for the full list, what each one covers, and an example policy.Authorizations
An OAuth 2.0 bearer token, sent as Authorization: Bearer <token>.
This is the recommended way to authenticate.
Get one by exchanging a service account's access key pair at
POST /v1/oauth/token with grant_type=client_credentials. It is the
standard client-credentials grant, so any OAuth-aware library will
obtain and refresh it for you.
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token
Tokens last an hour by default. The same access key pair is separately your AWS SigV4 credential for the S3-compatible object endpoint, which speaks nothing else.
Headers
Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token.
Maximum string length:
255Body
application/json
Unique per account. Surfaces in the CRN
(crn:certificate::<account>:certificate/<name>), so it must be
URL-safe — letters, digits, dot, dash, underscore. Resource names must not start with the literal crn: prefix or be UUIDs (canonical, compact, braced, or urn:uuid: forms, in either case).
Pattern:
^[a-zA-Z0-9][a-zA-Z0-9._-]{0,253}$Example:
"prod-frontend"
Capped at 100 to stay inside the certificate authority's per-order limits.
Required array length:
1 - 100 elementsExample:
[ "example.com", "www.example.com", "api.example.com" ]
Available options:
ecdsa-p256, ecdsa-p384, rsa-2048, rsa-4096 Defaults to "acme" — issued by the platform CA. Set to "uploaded" to store customer-supplied PEM material instead; certificate_pem + private_key_pem must then be provided.
Available options:
acme, uploaded Example:
"acme"
PEM-encoded leaf certificate. Required when source=uploaded.
Example:
"-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAaH...\n-----END CERTIFICATE-----\n"
PEM-encoded intermediate chain (optional when source=uploaded).
Example:
"-----BEGIN CERTIFICATE-----\nMIIEFzCCAv+gAwIBAgIEBb2...\n-----END CERTIFICATE-----\n"
PEM-encoded private key. Required when source=uploaded.
Example:
"-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEG...\n-----END PRIVATE KEY-----\n"
Show child attributes
Show child attributes
Example:
{ "environment": "production", "team": "backend" }
Response
Uploaded certificate stored (source=uploaded)
Show child attributes
Show child attributes