--- title: "Default Requests" description: "Store your usual issuer, profile and CRL settings once so each certificate issuance only sends the subject and validity." stack: "Enterprise Stack (commercial) — version 1.1.1" stack_version: "1.1.1" stack_comparison: https://docs.walt.id/community-vs-enterprise.md canonical_url: https://docs.walt.id/enterprise-stack/services/x509-service/default-requests generated: 2026-10-01 --- # 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. **Note:** Default requests are **optional**. Nothing on this page is required to issue certificates. Use it once you notice you are repeating the same issuer settings. ## 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: ```json { "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: ```json { "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. **Note:** **Send the request to the service, not to a certificate ID.** A default is applied only when the request `target` is the service itself (`{organizationID}.{tenantID}.{x509ServiceID}`). If the target ends in a certificate ID (`…{x509ServiceID}.{certificateID}`), the stored default is silently ignored. The service then generates a random certificate ID, which the response returns in `certificate._id`. Because `PUT /certificates` always requires a certificate ID in the target, a default stored for `upsert-certificate` currently has no effect. ## Prerequisites - An X.509 Certificate Service with a KMS and an X.509 Store attached. See [Setup](https://docs.walt.id/enterprise-stack/services/x509-service/setup.md). - A stored IACA to issue under. See [Issue Certificates](https://docs.walt.id/enterprise-stack/services/x509-service/issue-certificates.md#iso-iaca-root-certificate). - 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. **Option: CURL** **Endpoint:** `PUT /v1/{target}/x509-service-api/default-requests/create-certificate` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html) ##### Example Request ```bash 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" }' ``` **Path Parameters** - **orgID**: _String_ (required) - Organization host alias. For the sandbox organization `test`, the base URL is `https://test.enterprise-sandbox.waltid.dev`. - **target**: _resourceIdentifier_ (required) - `{organizationID}.{tenantID}.{x509ServiceID}`, for example `test.tenant1.x509-service-1`. **Header Parameters** - **Authorization**: _String_ (required) - Bearer token. Format: `Bearer {yourToken}`. **Body Parameters** - The body is a **partial** issuance request. It accepts the same fields as [issuing a certificate](https://docs.walt.id/enterprise-stack/services/x509-service/issue-certificates.md#request-fields), and you can send any subset of them. Unknown or misspelled keys, and values that break the request rules, are rejected now, not later when a certificate is issued. Missing required fields such as `validFrom` and `validTo` are not checked until you issue a certificate. ##### Example Response `200 OK` The stored document is echoed back. ```json { "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" } ``` **Response Codes** - `200` - Default request stored. - `400` - The document is not a valid partial body for this operation. - `401` / `403` - Authentication or authorization failure. `update-default-requests` and the operation's own permission are both required. - `404` - Service not found, or the operation name is unknown. ## Step 2: Issue a Certificate Send only what is specific to this certificate: its key and name, and its validity. **Option: CURL** **Endpoint:** `POST /v1/{target}/x509-service-api/certificates` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html) ##### Example Request ```bash 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" }' ``` **Path Parameters** - **orgID**: _String_ (required) - Organization host alias. - **target**: _resourceIdentifier_ (required) - `{organizationID}.{tenantID}.{x509ServiceID}`. Do not append a certificate ID, or the default is not applied. **Header Parameters** - **Authorization**: _String_ (required) - Bearer token. Format: `Bearer {yourToken}`. **Body Parameters** - Any field you send overrides the stored value. `validFrom` and `validTo` are always required, and so is one subject key source and, unless a CSR is used, `subjectDn`. ##### Example Response `201 Created` The response is the same as for any issuance. The stored `iso-document-signer` profile and issuer are applied, so the certificate is signed by the IACA and carries the stored CRL distribution point. See [Response model](https://docs.walt.id/enterprise-stack/services/x509-service/issue-certificates.md#response-model) for the fields. ```json { "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" } } ``` **Response Codes** - `200` - Certificate generated, no store attached (not persisted). - `201` - Certificate issued and persisted. - `400` - The merged request is not a valid issuance request, for example when neither the default nor the call provides an issuing certificate. - `401` / `403` - Authentication or authorization failure. ### 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](https://docs.walt.id/enterprise-stack/services/x509-service/csr-workflows.md). ```json { "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: ```json { "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](https://docs.walt.id/enterprise-stack/administration/services/configuration/default-requests.md).