---
title: "Setup"
description: "Create an X.509 Certificate Service when you need to issue certificates or CSRs through the Enterprise API."
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/setup
generated: 2026-10-01
---
# Setup

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

## Create the service

**Option: CURL**

Endpoint: `/v1/{target}/resource-api/services/create` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Service%20%2F%20Resource/post_v1__target__resource_api_services_create)

**Example Request**

```bash
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**

```json
{
  "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](#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](https://docs.walt.id/enterprise-stack/services/x509-service/issue-certificates.md#store-persistence)).

| Field | Values | Meaning |
|---|---|---|
| `createStrategy` | `CREATE_NONE` | The generated certificate is returned but not persisted. Forced automatically when no store is attached. |
| | `CREATE_ONE` | Write into one attached store. Fails if the certificate ID already exists in any attached store. |
| | `CREATE_ALL` | Write into every attached store using one shared child ID. Fails if the ID already exists in any store. |
| `upsertStrategy` | `INSERT_ONE_UPDATE_ALL` | Update the certificate in every store that already has it; insert into one store if it exists nowhere. |
| | `UPSERT_ALL` | Insert or update the certificate in every attached store. |
| `successStrategy` | `ANY_OK` | The request succeeds if at least one store write succeeds. |
| | `ALL_OK` | Every store write must succeed, otherwise the request fails. |

**Note:**

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.

**Option: CURL**

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

**Example Request**

```bash
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.

**Note:**

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.

**Option: CURL**

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

**Example Request**

```bash
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.

**Note:**

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](https://docs.walt.id/enterprise-stack/services/x509-service/issue-certificates.md) — issue roots, CA-signed certificates, IACAs and Document Signers.
- [CSR Workflows](https://docs.walt.id/enterprise-stack/services/x509-service/csr-workflows.md) — create CSRs and issue certificates from them.
- [Default Requests](https://docs.walt.id/enterprise-stack/services/x509-service/default-requests.md) — stop repeating the same issuer, profile and CRL settings on every Document Signer issuance. Save them once and send only the subject and validity.