REST PKI API - Certificate Enrollment¶

Trustpoint provides a simplified REST API for certificate enrollment and re-enrollment operations. This is a JSON-based alternative to the standard EST and CMP protocols, designed for ease of integration.

Note: This is the Certificate Enrollment API (/rest/). For general Trustpoint administration and management, see the Trustpoint Management API (/api/).

Overview¶

The REST PKI API allows devices and clients to:

Enroll for new certificates (/enroll)
Re-enroll existing certificates (/reenroll)

Base URL¶

All REST PKI endpoints are accessible under:

https://<trustpoint-host>/rest/

URL Structure¶

The REST API uses a simple URL structure with domain and optional certificate profile parameters:

With Domain and Certificate Profile¶

POST /rest/<domain>/<cert_profile>/enroll
POST /rest/<domain>/<cert_profile>/reenroll

With Domain Only (Default Profile)¶

POST /rest/<domain>/enroll

When the certificate profile is omitted, the default profile domain_credential is used.

URL Parameters¶

Path Parameters¶

Parameter	Description	Required	Example
`domain`	The Trustpoint domain name	Yes	`production`, `iot_domain`
`cert_profile`	Certificate profile identifier	No (defaults to `domain_credential`)	`device_cert`, `server_cert`

Endpoints¶

1. Enroll (Initial Certificate Request)¶

Request a new certificate from Trustpoint.

Endpoint: POST /<domain>/<cert_profile>/enroll

Authentication: Required (see Authentication)

Request Headers:

Content-Type: application/json
Authorization: Basic <base64-credentials>

Request Body (JSON):

{
    "csr": "<PEM or Base64-DER encoded PKCS#10 CSR>"
}

Response:

Status Code: 200 OK (success)
Content-Type: application/json

Response Body (JSON):

{
    "certificate": "<PEM certificate>",
    "certificate_chain": [
        "<PEM CA certificate>",
        "<PEM root certificate>",
        "..."
    ]
}

Example Request:

curl -X POST \
  https://trustpoint.example.com/rest/production/device_cert/enroll \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWEx\n...\n-----END CERTIFICATE REQUEST-----"
  }'

Example Response:

{
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKJ...\n-----END CERTIFICATE-----",
    "certificate_chain": [
        "-----BEGIN CERTIFICATE-----\nMIIDBTCCAe2gAwIBAgIQN...\n-----END CERTIFICATE-----",
        "-----BEGIN CERTIFICATE-----\nMIIDBjCCAe6gAwIBAgIBAD...\n-----END CERTIFICATE-----"
    ]
}

2. Re-enroll (Certificate Renewal)¶

Re-enroll an existing certificate (renewal with the same or new key).

Endpoint: POST /<domain>/<cert_profile>/reenroll

Authentication: Mutual TLS required (client certificate authentication)

Request Headers:

Content-Type: application/json

Request Body (JSON):

{
    "csr": "<PEM or Base64-DER encoded PKCS#10 CSR>"
}

Response:

Status Code: 200 OK (success)
Content-Type: application/json

Response Body (JSON):

{
    "certificate": "<PEM certificate>",
    "certificate_chain": [
        "<PEM CA certificate>",
        "<PEM root certificate>",
        "..."
    ]
}

Example Request:

curl -X POST \
  https://trustpoint.example.com/rest/production/device_cert/reenroll \
  -H "Content-Type: application/json" \
  --cert current_cert.pem \
  --key current_key.pem \
  -d '{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWEx\n...\n-----END CERTIFICATE REQUEST-----"
  }'

Example Response:

{
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKJ...\n-----END CERTIFICATE-----",
    "certificate_chain": [
        "-----BEGIN CERTIFICATE-----\nMIIDBTCCAe2gAwIBAgIQN...\n-----END CERTIFICATE-----"
    ]
}

Authentication¶

The REST PKI API supports two authentication methods:

1. HTTP Basic Authentication (Username/Password)¶

Used for initial enrollment when no certificate exists.

Header:

Authorization: Basic <base64-encoded-credentials>

Where <base64-encoded-credentials> is the base64 encoding of username:password.

Example:

# Username: device123, Password: secret
curl -X POST \
  https://trustpoint.example.com/rest/production/enroll \
  -H "Content-Type: application/json" \
  -u "device123:secret" \
  -d '{"csr": "..."}'

Use case: Initial device onboarding

2. Mutual TLS (mTLS)¶

Used for re-enrollment when the device already has a certificate.

Configuration: The client must present its current certificate during the TLS handshake.

Example:

curl -X POST \
  https://trustpoint.example.com/rest/production/reenroll \
  -H "Content-Type: application/json" \
  --cert client_cert.pem \
  --key client_key.pem \
  --cacert trustpoint_ca.pem \
  -d '{"csr": "..."}'

Use case: Certificate renewal, re-key operations

CSR Format¶

The Certificate Signing Request (CSR) can be provided in two formats:

1. PEM Format (Recommended)¶

{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWEx\nFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDzANBgNVBAoMBk15T3JnMRAwDgYDVQQL\nDAdNeVVuaXQxGDAWBgNVBAMMD015RGV2aWNlTmFtZTEwggEiMA0GCSqGSIb3DQEB\nAQUAA4IBDwAwggEKAoIBAQC...\n-----END CERTIFICATE REQUEST-----"
}

2. Base64-Encoded DER Format¶

{
    "csr": "MIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWEx..."
}

Response Status Codes¶

Status Code	Description
`200 OK`	Request processed successfully
`400 Bad Request`	Invalid request format, malformed JSON, or invalid CSR
`401 Unauthorized`	Authentication failed (invalid credentials or missing certificate)
`403 Forbidden`	Authorization failed (valid auth but insufficient permissions)
`404 Not Found`	Domain or certificate profile does not exist
`500 Internal Server Error`	Server error during processing

Error Response Format¶

When an error occurs, the API returns a JSON response with error details:

Example Error Response:

{
    "error": "Authentication failed",
    "detail": "Invalid username or password"
}

Common error scenarios:

400 Bad Request: Invalid JSON format, missing csr field, or malformed CSR
401 Unauthorized: Invalid username/password or missing/invalid client certificate
403 Forbidden: Valid authentication but insufficient permissions
404 Not Found: Specified domain or certificate profile does not exist
500 Internal Server Error: Server-side processing error (check server logs)