Setup

Create an X.509 Certificate Service when you need to issue certificates or CSRs through the Enterprise API.

Create the service

CURL

Endpoint: /v1/{target}/resource-api/services/create | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "x509-service"
}'

Body

{
  "type": "x509-service"
}

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 is test.enterprise-sandbox.waltid.dev on the sandbox environment.
  • target: resourceIdentifier - The organization + tenant in which to create the service and the new service's ID ({organizationID}.{tenantID}.[NewX509ServiceID]), e.g. test.tenant1.x509-service-1.

Body Parameters

  • type: serviceType - Specifies the type of service to create. In this case x509-service.
  • persistStrategy: Object (optional) - Default persistence strategy applied to every issuance request. Omit it to use the built-in default (CREATE_ONE / INSERT_ONE_UPDATE_ALL / ANY_OK). See Persistence strategy.
    • createStrategy: String - CREATE_ONE (write to one attached store) or CREATE_ALL (write to all attached stores). CREATE_NONE disables persistence.
    • upsertStrategy: String - INSERT_ONE_UPDATE_ALL or UPSERT_ALL.
    • successStrategy: String - ANY_OK (request succeeds if at least one store write succeeds) or ALL_OK (all store writes must succeed).

Response Codes

  • 201 - Service created successfully.

Persistence strategy

The persistence strategy controls how issued certificates are written across the attached X.509 Store services. It is set once on the service (persistStrategy above) and can be overridden per request via createStrategy / upsertStrategy / successStrategy / storeRef (see Issue Certificates).

FieldValuesMeaning
createStrategyCREATE_NONEThe generated certificate is returned but not persisted. Forced automatically when no store is attached.
CREATE_ONEWrite into one attached store. Fails if the certificate ID already exists in any attached store.
CREATE_ALLWrite into every attached store using one shared child ID. Fails if the ID already exists in any store.
upsertStrategyINSERT_ONE_UPDATE_ALLUpdate the certificate in every store that already has it; insert into one store if it exists nowhere.
UPSERT_ALLInsert or update the certificate in every attached store.
successStrategyANY_OKThe request succeeds if at least one store write succeeds.
ALL_OKEvery store write must succeed, otherwise the request fails.

When no X.509 Store service is attached, the service is fully stateless: createStrategy is treated as CREATE_NONE, PUT /certificates cannot be used, and the issuance response omits persistResult entries.

Attach a KMS service

Attach a KMS service to resolve keys referenced by issuerKeyRef / subjectKeyRef in issuance and CSR requests.

CURL

Endpoint: /v1/{target}/x509-service-api/dependencies/add

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-service-api/dependencies/add' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "dependency": "test.tenant1.kms1"
}'

Path Parameters

  • orgID: - When performing operations within an organization, use the organization's Base URL or another valid host alias.
  • target: resourceIdentifier - The organization + tenant + X.509 Certificate service to add the dependency to ({organizationID}.{tenantID}.{x509ServiceID}), e.g. test.tenant1.x509-service-1.

Body Parameters

  • dependency: String - Fully-qualified path of the KMS service to link, for example test.tenant1.kms1.

Response Codes

  • 201 - Dependency attached successfully.

Keys supplied directly as JWKs (issuerKeyJwk / subjectKeyJwk) are read from the request and need no KMS dependency.

Attach an X.509 Store service

Attach one or more X.509 Store services to persist issued certificates automatically.

CURL

Endpoint: /v1/{target}/x509-service-api/dependencies/add

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-service-api/dependencies/add' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "dependency": "test.tenant1.x509-store-1"
}'

Path Parameters

  • orgID: - When performing operations within an organization, use the organization's Base URL or another valid host alias.
  • target: resourceIdentifier - The organization + tenant + X.509 Certificate service to add the dependency to ({organizationID}.{tenantID}.{x509ServiceID}), e.g. test.tenant1.x509-service-1.

Body Parameters

  • dependency: String - Fully-qualified path of the X.509 Store service to link, for example test.tenant1.x509-store-1.

Response Codes

  • 201 - Dependency attached successfully.

Attach the store services before issuing certificates you want persisted. Each issuance request uses one shared child certificate ID across all attached stores; the response returns the resulting full stored certificate paths in persistResult.

Next Steps

  • Issue Certificates — issue roots, CA-signed certificates, IACAs and Document Signers.
  • CSR Workflows — create CSRs and issue certificates from them.
  • Default Requests — stop repeating the same issuer, profile and CRL settings on every Document Signer issuance. Save them once and send only the subject and validity.
Last updated on September 29, 2026
OverviewIssue Certificates