#Default Requests

Issuing a certificate takes a long request: profile, issuing certificate, alternative names, CRL URI, key usage, and then the parts that are actually specific to this certificate. Default requests let you save the repeated part once on your X.509 Certificate Service, so an issuance only carries what is unique to it.

#When This Is Worth It

Default requests pay off when many certificates share the same issuer and profile and differ only in subject and validity. In the X.509 service that is for example:

• Document Signer issuance under one IACA. Every Document Signer is iso-document-signer, signed by the same IACA, with the same issuer alternative name and CRL URI. Only the signer's key or CSR, its name and its validity change. This is the case this page walks through.
• CSR-based issuance for partners. Requesters submit a CSR and you sign it under a fixed issuer. With the issuer settings stored, the call is just csrPem plus validity.

They are a poor fit for one-off certificates. An IACA root, for example, is issued once in the life of a program, so there is nothing to repeat.

#What Changes

Without a default, every Document Signer issuance carries the full body:

{
  "certificateProfile": "iso-document-signer",
  "issuerCertificateRef": "test.tenant1.x509-store-1.iaca-prod-2026",
  "issuerAlternativeNames": [
    { "type": "uri", "name": "https://iaca.example.com" }
  ],
  "crlDistributionPointUri": "https://crl.example.com/ds.crl",
  "subjectKeyRef": "test.tenant1.kms1.ds-key",
  "subjectDn": "CN=Example Document Signer,O=Example Org,C=US",
  "validFrom": "2026-09-01T00:00:00Z",
  "validTo": "2027-11-01T00:00:00Z"
}

With the first four fields stored as a default, the call becomes:

{
  "subjectKeyRef": "test.tenant1.kms1.ds-key",
  "subjectDn": "CN=Example Document Signer,O=Example Org,C=US",
  "validFrom": "2026-09-01T00:00:00Z",
  "validTo": "2027-11-01T00:00:00Z"
}

The service fills in everything you left out. Anything you do send in the call wins over the stored value.

#Prerequisites

• An X.509 Certificate Service with a KMS and an X.509 Store attached. See Setup.
• A stored IACA to issue under. See Issue Certificates.
• A bearer token with the update-default-requests permission and the permission to create certificates. Both are needed to store a default.

#Step 1: Store a Default

Store the issuer settings with a PUT. The last part of the URL, create-certificate, names the API call the default applies to: the one behind POST /v1/{target}/x509-service-api/certificates. The body is an ordinary certificate issuance request. Leave out every field that changes per certificate.

curl -X 'PUT' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-service-api/default-requests/create-certificate' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "certificateProfile": "iso-document-signer",
  "issuerCertificateRef": "test.tenant1.x509-store-1.iaca-prod-2026",
  "issuerAlternativeNames": [
    { "type": "uri", "name": "https://iaca.example.com" }
  ],
  "crlDistributionPointUri": "https://crl.example.com/ds.crl"
}'

{
  "certificateProfile": "iso-document-signer",
  "issuerCertificateRef": "test.tenant1.x509-store-1.iaca-prod-2026",
  "issuerAlternativeNames": [
    { "type": "uri", "name": "https://iaca.example.com" }
  ],
  "crlDistributionPointUri": "https://crl.example.com/ds.crl"
}

#Step 2: Issue a Certificate

Send only what is specific to this certificate: its key and name, and its validity.

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-service-api/certificates' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "subjectKeyRef": "test.tenant1.kms1.ds-key",
  "subjectDn": "CN=Example Document Signer,O=Example Org,C=US",
  "validFrom": "2026-09-01T00:00:00Z",
  "validTo": "2027-11-01T00:00:00Z"
}'

{
  "certificate": {
    "_id": "test.tenant1.x509-store-1.c23b32a3-f7d2-4388-9e43-2d69f71de017",
    "issuerDn": "CN=Example IACA,O=Example Org,C=US",
    "subjectDn": "CN=Example Document Signer,O=Example Org,C=US",
    "validFrom": "2026-09-01T00:00:00Z",
    "validTo": "2027-11-01T00:00:00Z",
    "certificatePem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "persistResult": {
    "test.tenant1.x509-store-1.c23b32a3-f7d2-4388-9e43-2d69f71de017": "CREATED"
  }
}

#Issue from a CSR

The same default works for CSR-based issuance. Send the CSR and the validity, and the stored issuer settings do the rest. See CSR Workflows.

{
  "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\nMIIB...\n-----END CERTIFICATE REQUEST-----",
  "validFrom": "2026-09-01T00:00:00Z",
  "validTo": "2027-11-01T00:00:00Z"
}

#Override Part of the Default

To change one thing, send only that. This request uses a different CRL distribution point and keeps everything else from the default:

{
  "subjectKeyRef": "test.tenant1.kms1.ds-key",
  "subjectDn": "CN=Example Document Signer,O=Example Org,C=US",
  "validFrom": "2026-09-01T00:00:00Z",
  "validTo": "2027-11-01T00:00:00Z",
  "crlDistributionPointUri": "https://crl.other.example.com/ds.crl"
}

#Read or Remove a Default

• List all stored defaults: GET /v1/{target}/x509-service-api/default-requests (needs view-default-requests).
• Read one: GET …/default-requests/create-certificate. Returns 404 if none is stored.
• Remove one: DELETE …/default-requests/create-certificate. Returns 204, also when nothing was stored.

Full details, permissions and the other services that support default requests: Default Requests.