Manage Certificates

Use the X.509 Store Service to store generic certificates or VICAL entries, list what is already stored, and manage individual entries by full target path.

Service reference: Swagger API Reference

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: For list and list-ids, use the X.509 Store service path ({organizationID}.{tenantID}.{x509StoreServiceID}), for example test.tenant1.x509-store-1. For add, use the store path to generate a certificate ID automatically, or use a full child certificate path to choose the ID yourself, for example test.tenant1.x509-store-1.base-001. For get, update, and delete, use the full stored certificate path.

List stored certificates

CURL

Endpoint: /v1/{target}/x509-store-api/certificates

curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-store-api/certificates?limit=50&offset=0&sort=createdDateTime' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

Query Parameters

  • limit: Integer (optional) – Maximum number of entries to return. Defaults to 100.
  • offset: Integer (optional) – Number of entries to skip. Defaults to 0.
  • sort: String (optional) – One of createdDateTime, createdDateTime:asc, createdDateTime:desc, updatedDateTime, updatedDateTime:asc, updatedDateTime:desc.

Invalid values return 400 Bad Request — see the pagination reference for the full contract.

Example Response

[
  {
    "_id": "org1.tenant1.x509-store-1.base-001",
    "createdAt": "2026-08-20T12:34:13.453521061Z",
    "updatedAt": "2026-08-20T12:34:13.453521061Z",
    "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
    "issuerDn": "C=US,CN=Example IACA",
    "issuerDnHex": "3024310b30090603550406130255533115301306035504030c0c4578616d706c652049414341",
    "subjectDn": "C=US,CN=Example DS",
    "subjectDnHex": "3022310b30090603550406130255533113301106035504030c0a4578616d706c65204453",
    "validFrom": "2025-05-29T07:18:39Z",
    "validTo": "2026-08-29T07:18:39Z",
    "parent": "org1.tenant1.x509-store-1"
  },
  {
    "_id": "org1.tenant1.x509-store-1.vical-001",
    "createdAt": "2026-08-20T12:34:13.454642800Z",
    "updatedAt": "2026-08-20T12:34:13.454642800Z",
    "metadata": {
      "vicalDocType": [
        "org.iso.18013.5.1.mDL"
      ],
      "vicalCertProfile": [
        "1.0.18013.5.1.7"
      ]
    },
    "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
    "issuerDn": "C=US,CN=Example IACA",
    "issuerDnHex": "3024310b30090603550406130255533115301306035504030c0c4578616d706c652049414341",
    "subjectDn": "C=US,CN=Example IACA",
    "subjectDnHex": "3024310b30090603550406130255533115301306035504030c0c4578616d706c652049414341",
    "validFrom": "2025-05-28T12:23:01Z",
    "validTo": "2040-05-24T12:23:01Z",
    "parent": "org1.tenant1.x509-store-1"
  }
]

Response Codes

  • 200 - Stored certificates retrieved successfully.

List stored certificate IDs

CURL

Endpoint: /v1/{target}/x509-store-api/certificates/ids

curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-store-api/certificates/ids?limit=50&offset=0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

Query Parameters

  • limit: Integer (optional) – Maximum number of entries to return. Defaults to 100.
  • offset: Integer (optional) – Number of entries to skip. Defaults to 0.

sort is not supported on this endpoint. Invalid values return 400 Bad Request — see the pagination reference for the full contract.

Example Response

[
  "test.tenant1.x509-store-1.base-001",
  "test.tenant1.x509-store-1.vical-001"
]

Response Codes

  • 200 - Stored certificate IDs retrieved successfully.

Add a certificate

Use the store target to generate a certificate ID automatically. Use a full child certificate target, such as test.tenant1.x509-store-1.base-001, when you want to choose the stored certificate ID.

CURL

Endpoint: /v1/{target}/x509-store-api/certificates

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-store-api/certificates' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
}'

Body Parameters

  • certificatePem: PEM-encoded X.509 certificate to store.

Example Response

{
  "_id": "org1.tenant1.x509-store-1.base-001",
  "createdAt": "2026-08-20T12:34:13.453521061Z",
  "updatedAt": "2026-08-20T12:34:13.453521061Z",
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "issuerDn": "C=US,CN=Example IACA",
  "issuerDnHex": "3024310b30090603550406130255533115301306035504030c0c4578616d706c652049414341",
  "subjectDn": "C=US,CN=Example DS",
  "subjectDnHex": "3022310b30090603550406130255533113301106035504030c0a4578616d706c65204453",
  "validFrom": "2025-05-29T07:18:39Z",
  "validTo": "2026-08-29T07:18:39Z",
  "parent": "org1.tenant1.x509-store-1"
}

Response Codes

  • 201 - Certificate stored successfully.

The stored certificate ID comes from the request target. When the target is the store itself, the service generates a UUID child ID.

Add a certificate with VICAL metadata

Use the store target to generate a certificate ID automatically. Use a full child certificate target, such as test.tenant1.x509-store-1.vical-001, when you want to choose the stored certificate ID.

CURL

Endpoint: /v1/{target}/x509-store-api/certificates

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-store-api/certificates' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "metadata": {
    "vicalDocType": [
      "org.iso.18013.5.1.mDL"
    ],
    "vicalCertProfile": [
      "1.0.18013.5.1.7"
    ]
  }
}'

Body Parameters

  • certificatePem: PEM-encoded IACA root certificate to store.
  • metadata.vicalDocType: Required list of document types covered by the IACA root certificate.
  • metadata.vicalCertProfile: Optional list of certificate-profile identifiers to store with the entry.

Example Response

{
  "_id": "org1.tenant1.x509-store-1.vical-001",
  "createdAt": "2026-08-20T12:34:13.454642800Z",
  "updatedAt": "2026-08-20T12:34:13.454642800Z",
  "metadata": {
    "vicalDocType": [
      "org.iso.18013.5.1.mDL"
    ],
    "vicalCertProfile": [
      "1.0.18013.5.1.7"
    ]
  },
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "issuerDn": "C=US,CN=Example IACA",
  "issuerDnHex": "3024310b30090603550406130255533115301306035504030c0c4578616d706c652049414341",
  "subjectDn": "C=US,CN=Example IACA",
  "subjectDnHex": "3024310b30090603550406130255533115301306035504030c0c4578616d706c652049414341",
  "validFrom": "2025-05-28T12:23:01Z",
  "validTo": "2040-05-24T12:23:01Z",
  "parent": "org1.tenant1.x509-store-1"
}

Response Codes

  • 201 - VICAL entry stored successfully.

Get a stored certificate

CURL

Endpoint: /v1/{target}/x509-store-api/certificates

curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-store-api/certificates' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

Example Response

{
  "_id": "org1.tenant1.x509-store-1.vical-001",
  "createdAt": "2026-08-20T12:34:13.454642800Z",
  "updatedAt": "2026-08-20T12:34:13.454642800Z",
  "metadata": {
    "vicalDocType": [
      "org.iso.18013.5.1.mDL"
    ],
    "vicalCertProfile": [
      "1.0.18013.5.1.7"
    ]
  },
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "issuerDn": "C=US,CN=Example IACA",
  "issuerDnHex": "3024310b30090603550406130255533115301306035504030c0c4578616d706c652049414341",
  "subjectDn": "C=US,CN=Example IACA",
  "subjectDnHex": "3024310b30090603550406130255533115301306035504030c0c4578616d706c652049414341",
  "validFrom": "2025-05-28T12:23:01Z",
  "validTo": "2040-05-24T12:23:01Z",
  "parent": "org1.tenant1.x509-store-1"
}

Response Codes

  • 200 - Stored certificate retrieved successfully.

Insert or update a stored certificate (idempotent)

CURL

Endpoint: /v1/{target}/x509-store-api/certificates

curl -X 'PUT' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-store-api/certificates' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "metadata": {
    "vicalDocType": [
      "org.iso.18013.5.1.mDL"
    ],
    "vicalCertProfile": [
      "1.0.18013.5.1.7"
    ]
  }
}'

Body Parameters

  • certificatePem: PEM-encoded certificate that should replace the current stored payload.
  • metadata: Required when certificate should be exported as VICAL.

The target identifies which stored certificate is updated. You can add or remove VICAL metadata on update by including or omitting the metadata field.

Response Codes

  • 200 - Certificate updated successfully.
  • 201 - Certificate was created.

Delete a stored certificate

CURL

Endpoint: /v1/{target}/x509-store-api/certificates

curl -X 'DELETE' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/x509-store-api/certificates' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}'

Response Codes

  • 200 - Certificate deleted successfully.
Last updated on August 24, 2026
SetupX.509 Store Service