#Issue Certificates

Use the X.509 Certificate Service to issue IACA root certificates and Document Signer certificates for ISO/IEC 18013-5 deployments.

Service reference: Swagger API Reference

If one or more X.509 Store services are attached, the service uses one shared storedCertificateId child ID across all attached stores. When you omit storedCertificateId, the service generates a UUID automatically. If no store is attached, the field is ignored and storedCertificateIds is omitted from the response.

#Shared Path Parameters

orgID: When performing operations within an organization, use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.waltid.dev when using the sandbox environment.
target: The full X.509 Certificate service path ({organizationID}.{tenantID}.{x509ServiceID}), for example test.tenant1.x509-service-1.

#Create an IACA certificate

CURL

Endpoint: /v1/{target}/x509-service-api/iso/iacas | API Reference

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-service-api/iso/iacas' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "storedCertificateId": "iaca-prod-2026-q1",
  "certificateData": {
    "country": "US",
    "commonName": "Example IACA",
    "issuerAlternativeNameConf": {
      "uri": "https://iaca.example.com"
    }
  },
  "vicalEntryComplementaryMetadata": {
    "docType": ["org.iso.18013.5.1.mDL"],
    "certificateProfile": ["org.iso.18013.5.1.iaca"]
  },
  "iacaKeyDesc": {
    "type": "kms-hosted-key-descriptor",
    "keyIdPath": "test.tenant1.kms1.secp256r1"
  }
}'

Body Parameters

certificateData: Subject and validity data for the generated IACA certificate.
iacaKeyDesc: Signing key descriptor. Use either kms-hosted-key-descriptor or jwk-encoded-key-descriptor.
storedCertificateId: Optional child certificate ID used when one or more X.509 Store dependencies are attached. The response returns the resulting full stored certificate paths in storedCertificateIds.
vicalEntryComplementaryMetadata: Optional metadata. When provided and stores are attached, the issued IACA is stored as a VICAL entry; otherwise it is stored as a generic certificate.

Example Response

{
  "certificatePEM": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "storedCertificateIds": [
    "test.tenant1.x509-store-1.iaca-prod-2026-q1"
  ],
  "certificateData": {
    "country": "US",
    "commonName": "Example IACA",
    "notBefore": "<generated-timestamp>",
    "notAfter": "<generated-timestamp>",
    "issuerAlternativeNameConf": {
      "uri": "https://iaca.example.com"
    }
  }
}

Response Codes

200 - IACA certificate issued successfully.

If no X.509 Store dependency is attached, storedCertificateId is ignored on the request and storedCertificateIds is omitted from the response.

#Create a Document Signer certificate

CURL

Endpoint: /v1/{target}/x509-service-api/iso/document-signers | API Reference

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-service-api/iso/document-signers' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "storedCertificateId": "ds-mainline-2026-01",
  "iacaSigner": {
    "type": "iaca-cert-data-descriptor",
    "iacaKeyDesc": {
      "type": "kms-hosted-key-descriptor",
      "keyIdPath": "test.tenant1.kms1.iaca-secp256r1"
    },
    "certificateData": {
      "country": "US",
      "commonName": "Example IACA",
      "notBefore": "2025-05-28T12:23:01Z",
      "notAfter": "2040-05-24T12:23:01Z",
      "issuerAlternativeNameConf": {
        "uri": "https://iaca.example.com"
      }
    }
  },
  "certificateData": {
    "country": "US",
    "commonName": "Example DS",
    "crlDistributionPointUri": "https://crl-example.com"
  },
  "dsKeyDescriptor": {
    "type": "kms-hosted-key-descriptor",
    "keyIdPath": "test.tenant1.kms1.ds-secp256r1"
  }
}'

Body Parameters

iacaSigner: Describes the IACA used to issue the Document Signer certificate. Use either iaca-cert-data-descriptor or iaca-pem-cert-descriptor.
certificateData: Subject and validity data for the generated Document Signer certificate.
dsKeyDescriptor: Key descriptor for the Document Signer key. Use either kms-hosted-key-descriptor or jwk-encoded-key-descriptor.
storedCertificateId: Optional child certificate ID used when one or more X.509 Store dependencies are attached. The response returns the resulting full stored certificate paths in storedCertificateIds.

Example Response

{
  "certificatePEM": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "storedCertificateIds": [
    "test.tenant1.x509-store-1.ds-mainline-2026-01"
  ],
  "certificateData": {
    "country": "US",
    "commonName": "Example DS",
    "notBefore": "<generated-timestamp>",
    "notAfter": "<generated-timestamp>",
    "crlDistributionPointUri": "https://crl-example.com"
  }
}

Response Codes

200 - Document Signer certificate issued successfully.

If a provided storedCertificateId already exists in any attached X.509 Store, or if any attached store write fails, the issuance request fails.

Last updated on April 22, 2026

Setup X.509 Certificate Service