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

List stored certificates

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

CURL
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": "test.tenant1.x509-store-1.base-001",
    "data": {
      "type": "base",
      "pem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
    }
  },
  {
    "_id": "test.tenant1.x509-store-1.vical-001",
    "data": {
      "type": "vical-entry",
      "pem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
      "complementaryMetadata": {
        "docType": ["org.iso.18013.5.1.mDL"],
        "certificateProfile": ["1.0.18013.5.1.7"]
      }
    }
  }
]

Response Codes

  • 200 - Stored certificates retrieved successfully.

List stored certificate IDs

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

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

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 base certificate

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

CURL
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 '{
  "type": "base",
  "id": "base-001",
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
}'

Example Response

{
  "_id": "test.tenant1.x509-store-1.base-001",
  "data": {
    "type": "base",
    "pem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
  }
}

Body Parameters

  • type: Set to base to store a generic X.509 certificate entry.
  • id: Optional certificate ID suffix. If omitted, the X.509 Store Service generates one automatically.
  • certificatePem: PEM-encoded X.509 certificate to store.

Response Codes

  • 201 - Certificate stored successfully.

id is optional. If omitted, the X.509 Store Service generates one.

Add a VICAL entry

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

CURL
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 '{
  "type": "vical-entry",
  "id": "vical-001",
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "complementaryMetadata": {
    "docType": ["org.iso.18013.5.1.mDL"],
    "certificateProfile": ["1.0.18013.5.1.7"]
  }
}'

Example Response

{
  "_id": "test.tenant1.x509-store-1.vical-001",
  "data": {
    "type": "vical-entry",
    "pem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
    "complementaryMetadata": {
      "docType": ["org.iso.18013.5.1.mDL"],
      "certificateProfile": ["1.0.18013.5.1.7"]
    }
  }
}

Body Parameters

  • type: Set to vical-entry to store an IACA certificate plus VICAL metadata.
  • id: Optional certificate ID suffix. If omitted, the X.509 Store Service generates one automatically.
  • certificatePem: PEM-encoded IACA certificate to store.
  • complementaryMetadata.docType: Required list of document types covered by the IACA certificate.
  • complementaryMetadata.certificateProfile: Optional list of certificate-profile identifiers to store with the entry.

Response Codes

  • 201 - VICAL entry stored successfully.

A vical-entry requires an IACA certificate and complementaryMetadata.docType.

Get a stored certificate

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

CURL
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": "test.tenant1.x509-store-1.vical-001",
  "data": {
    "type": "vical-entry",
    "pem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
    "complementaryMetadata": {
      "docType": ["org.iso.18013.5.1.mDL"],
      "certificateProfile": ["1.0.18013.5.1.7"]
    }
  }
}

Response Codes

  • 200 - Stored certificate retrieved successfully.

Update a stored certificate

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

CURL
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 '{
  "type": "vical-entry",
  "certificatePem": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
  "complementaryMetadata": {
    "docType": ["org.iso.18013.5.1.mDL"],
    "certificateProfile": ["1.0.18013.5.1.7"]
  }
}'

Body Parameters

  • type: Use base to replace the stored entry with a generic certificate, or vical-entry to replace it with an IACA certificate plus VICAL metadata.
  • certificatePem: PEM-encoded certificate that should replace the current stored payload.
  • complementaryMetadata: Required when type is vical-entry.

The target identifies which stored certificate is updated. You can switch between base and vical-entry on update.

Response Codes

  • 204 - Certificate updated successfully.

Delete a stored certificate

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

CURL
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 March 12, 2026
SetupX.509 Store Service