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

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

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
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",
  "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.
  • certificatePem: PEM-encoded X.509 certificate to store.

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 VICAL entry

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

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
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",
  "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.
  • 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 a valid IACA certificate and non-empty complementaryMetadata.docType. certificateProfile, when provided, must also be non-empty.

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 April 22, 2026
SetupX.509 Store Service