PKI Configuration

PKI endpoints define the certificate authorities that IDIAL uses for issuing certificates to managed OPC UA devices. Each inventory entry is assigned a PKI endpoint. This determines which CA issues the certificate for the respective device and which trust list is provisioned on the device.

GET /pki

Returns all PKI endpoints configured in IDIAL.

Authentication: X-API-Key required

Response 200

Array of PKI endpoint configuration objects.

[
  {
    "id": 1,
    "name": "Production EST",
    "url": "https://est.example.com/.well-known/est",
    "auth_method": "basic_auth",
    "tls_validation": "standard"
  }
]

GET /pki/ca

Downloads the CA certificate from the configured PKI endpoint in PEM or DER format. Used to verify that IDIAL is connected to the correct certificate authority.

Authentication: X-API-Key required

Response 200: Binary CA certificate (PEM or DER).

GET /pki/crl

Downloads the Certificate Revocation List (CRL) from the configured PKI endpoint in PEM or DER format.

Authentication: X-API-Key required

Response 200: Binary CRL (PEM or DER).

GET /pki/est

Returns all EST endpoint configurations managed in IDIAL. This endpoint is used to retrieve the current EST configuration from IDIAL. The returned id is required for all modification operations on EST configurations.

Authentication: X-API-Key required

Response 200

Array of EST configuration objects:

[
  {
    "id": 1,
    "last_validated": "2026-03-06 10:30:45",
    "server": "est.example.com",
    "port": 8443,
    "enroll_endpoint": "/.well-known/est/profile1/simpleenroll",
    "renew_endpoint": "/.well-known/est/profile1/simplereenroll",
    "username": "estuser",
    "password_hash": "a1b2c3d4e5f6...",
    "enroll_auth": "basic",
    "renew_auth": "certificate",
    "tlschain": "MIIBxDCC...",
    "cacert": "MIIBxDCC...",
    "description": "Production EST Endpoint"
  }
]

Response Fields

Field	Type	Description
`id`	integer	Unique identifier of the EST configuration. Required for all modification operations.
`last_validated`	string	Date and time of the last successful validation. Empty if the EST endpoint has not yet been validated — in this case it cannot be assigned to any managed device.
`server`	string	IP address or DNS FQDN of the EST server. The EST server's server certificate should contain this value in the SAN attribute for IDIAL to successfully perform TLS server authentication. If a DNS FQDN is provided, it must be resolvable by IDIAL.
`port`	integer	Network port of the EST server endpoint.
`enroll_endpoint`	string	URI on the server for initial certificate issuance; corresponds to the `/simpleenroll` endpoint in the EST standard.
`renew_endpoint`	string	URI on the server for certificate renewal; corresponds to the `/simplereenroll` endpoint in the EST standard. By default, IDIAL expects TLS client authentication with the certificate to be renewed.
`username`	string	Username for basic authentication, if configured.
`password_hash`	string	SHA-256 hash of the current basic auth password. For security reasons, no plaintext password is returned. The password can be changed via the update endpoint.
`enroll_auth`	string	Currently configured authentication method for the `/simpleenroll` endpoint.
`renew_auth`	string	Currently configured authentication method for the `/simplereenroll` endpoint.
`tlschain`	string	Base64-encoded PKCS7 object of the trust chain of the EST server certificate. Allows verification that the correct trust chain is configured for TLS server certificate validation. Contains the chain from the EST server issuing CA certificate to the root CA certificate.
`cacert`	string	Base64-encoded PKCS7 object of the root CA certificates provided by the EST server. Only available if the EST server offers the `/cacerts` endpoint per RFC 7030.
`description`	string	Descriptive name of the EST endpoint for easier identification in the user interface.

Response 500

{"error": "string"}

POST /pki/est

Adds a new EST endpoint to IDIAL. IDIAL uses EST to issue and renew certificates for connected devices and workloads. It is common to configure multiple EST endpoints, as different certificate templates are required for different device categories or organizational requirements.

note

The EST endpoint is created in IDIAL but is not validated during this phase. To validate the endpoint, a call to /pki/est/validate must follow. After successful validation, the last_validated field contains the timestamp of the last successful connection.

The following example illustrates the structure of the EST connection URL:

EST URL:
https://server-fqdn.domain:8443/.well-known/est/profile1/simpleenroll
\________________/ \__/ \___________________________________/
server       port    enroll_endpoint / renew_endpoint

Authentication: X-API-Key required

Request Body

{
  "server": "est.example.com",
  "port": 8443,
  "enroll_endpoint": "/.well-known/est/profile1/simpleenroll",
  "renew_endpoint": "/.well-known/est/profile1/simplereenroll",
  "username": "estuser",
  "password": "secret",
  "enroll_auth": "basic",
  "renew_auth": "certificate",
  "tlschain": "MIIBxDCC...",
  "validate_server": true,
  "description": "Production EST Endpoint"
}

Request Fields

Field	Type	Required	Description
`server`	string	Yes	IP address or FQDN of the EST enrollment server.
`port`	string	Yes	Port on which the EST enrollment server is listening.
`enroll_endpoint`	string	Yes	URI for initial or recurring certificate issuance for a certificate template.
`renew_endpoint`	string	Yes	URI for certificate renewal.
`username`	string	No	Username for basic authentication at the EST endpoints configured for basic auth. If no basic auth credentials are defined, this authentication method cannot be assigned to any endpoint — IDIAL will respond with an error in this case.
`password`	string	No	Password for basic authentication. An empty password is not permitted — if submitted empty, the request behaves as if neither `username` nor `password` were sent.
`enroll_auth`	string	No	Authentication method for the `enroll_endpoint`.
`renew_auth`	string	No	Authentication method for the `renew_endpoint`.
`tlschain`	string	No	Base64-encoded PKCS7 format of the trust chain of the EST server certificate. This chain is used to validate the TLS server certificate and should extend from the EST server issuing CA certificate to the root CA certificate. IDIAL refuses connections to an unvalidated EST server.
`validate_server`	boolean	No	Default: `true`. IDIAL validates the EST server TLS connection and server certificate by default. Can be set to `false` to skip validation. Recommendation: Keep server validation enabled to ensure certificates are only issued via trusted and validated endpoints.
`description`	string	No	Descriptive name of the EST endpoint. Displayed in the user interface instead of the `id`.

warning

validate_server: false disables TLS server certificate validation. This should only be used in controlled test environments. In production environments, server validation is a critical security feature that ensures IDIAL only issues certificates via trusted and validated connections.

Response 200

{"id": 1}

The id of the newly created EST entry is returned in the response body.

Response 500

{"error": "string"}

DELETE /pki/est/{id}

Deletes a defined EST endpoint by its {id} in the URL.

warning

The EST endpoint must no longer be assigned to any managed device or workload in IDIAL. If it is still assigned, the service will respond with an error. All affected workloads must first be reconfigured to a different enrollment endpoint before the EST endpoint can be deleted.

Authentication: X-API-Key required

Path Parameters

Parameter	Description
`{id}`	ID of the EST endpoint in the IDIAL database to be deleted.

Response 200

The EST endpoint was successfully deleted.

Error Response (EST endpoint still in use)

{
  "in_use": [1, 2, 3],
  "error": "string"
}

The in_use field contains the IDs of the IDIAL endpoints that are still using the EST endpoint to be deleted.

PATCH /pki/est/{id}

Updates an existing EST endpoint configuration. The request can contain one or more attributes to update.

note

After updating the EST endpoint configuration, the last_validated flag is reset. Subsequently, /pki/est/validate/{id} must be called to perform re-validation and ensure that IDIAL can reach and use the endpoint.

Authentication: X-API-Key required

Request Body

Identical to POST /pki/est. Only the submitted fields are updated.

{
  "server": "est.example.com",
  "port": 8443,
  "enroll_endpoint": "/.well-known/est/profile1/simpleenroll",
  "renew_endpoint": "/.well-known/est/profile1/simplereenroll",
  "username": "estuser",
  "password": "secret",
  "enroll_auth": "basic",
  "renew_auth": "certificate",
  "tlschain": "MIIBxDCC...",
  "validate_server": true,
  "description": "Production EST Endpoint"
}

Response 200

The EST endpoint was successfully updated.

Response 500

{"error": "string"}

POST /pki/sign-client-csr

Signs a client CSR (Certificate Signing Request) via the configured PKI protocol. Supports EST, CMP, and internal protocols. Returns the signed X.509 certificate in PEM format.

Authentication: X-API-Key required

Request Body

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "pki_protocol": "internal"
}

Field	Type	Required	Default	Description
`csr`	string	Yes	—	PEM-formatted Certificate Signing Request
`pki_protocol`	string	No	`"internal"`	Protocol: `"internal"`, `"est"`, or `"cmp"`

Response 200

{
  "x509": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
}

note

The "est" and "cmp" protocols are intended for a future implementation phase. Currently, only "internal" is fully supported. When using "est" or "cmp", the endpoint returns HTTP 501.

POST /pki/sign-server-csr

Equivalent to POST /pki/sign-client-csr, but signs a server CSR. Returns the signed X.509 certificate.

Authentication: X-API-Key required

Request and Response: Identical to POST /pki/sign-client-csr.

Examples

# List PKI endpoints
curl -X GET http://localhost:5000/pki \
  -H "X-API-Key: your-api-key"

# Download CA certificate
curl -X GET http://localhost:5000/pki/ca \
  -H "X-API-Key: your-api-key" \
  -o ca.pem

# List all EST endpoints
curl -X GET http://localhost:5000/pki/est \
  -H "X-API-Key: your-api-key"

# Add a new EST endpoint
curl -X POST http://localhost:5000/pki/est \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "est.example.com",
    "port": 8443,
    "enroll_endpoint": "/.well-known/est/profile1/simpleenroll",
    "renew_endpoint": "/.well-known/est/profile1/simplereenroll",
    "validate_server": true,
    "description": "Production EST"
  }'

# Delete an EST endpoint
curl -X DELETE http://localhost:5000/pki/est/1 \
  -H "X-API-Key: your-api-key"

# Sign a client CSR
curl -X POST http://localhost:5000/pki/sign-client-csr \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
    "pki_protocol": "internal"
  }'

GET /pki​

Response 200​

GET /pki/ca​

GET /pki/crl​

GET /pki/est​

Response 200​

Response Fields​

Response 500​

POST /pki/est​

Request Body​

Request Fields​

Response 200​

Response 500​

DELETE /pki/est/{id}​

Path Parameters​

Response 200​

Error Response (EST endpoint still in use)​

PATCH /pki/est/{id}​

Request Body​

Response 200​

Response 500​

POST /pki/sign-client-csr​

Request Body​

Response 200​

POST /pki/sign-server-csr​

Examples​

GET /pki

Response 200

GET /pki/ca

GET /pki/crl

GET /pki/est

Response 200

Response Fields

Response 500

POST /pki/est

Request Body

Request Fields

Response 200

Response 500

DELETE /pki/est/{id}

Path Parameters

Response 200

Error Response (EST endpoint still in use)

PATCH /pki/est/{id}

Request Body

Response 200

Response 500

POST /pki/sign-client-csr

Request Body

Response 200

POST /pki/sign-server-csr

Examples