Certificate Enrollment via API

Concept

The API enrollment method allows you to issue certificates against a specific certificate profile over Web UI or by making an API request to Hanzo KMS.

Guide to Certificate Enrollment via API

In the following steps, we explore how to issue a X.509 certificate using the API enrollment method.

Create a certificate profile with API selected as the enrollment method.

Notice that the API enrollment method supports an option called Enable Auto-Renewal By Default. If selected, eligible certificates are automatically considered for server-side auto-renewal based on a specified renewal days before expiration threshold at the time of issuance; for more information about server-side auto-renewal, refer to the documentation here.

To create a certificate, head to your Project > Certificates > Certificate Requests and press Request.

pki certificates

Here, select the certificate profile from step 1 that will be used to issue the certificate and fill out the rest of the details for the certificate to be issued.

pki certificate issue modal

Once you have created the certificate from step 1, you'll be presented with the certificate details including the Certificate Body, Certificate Chain, and Private Key.

pki certificate body

Make sure to download and store the Private Key in a secure location as it will only be displayed once at the time of certificate issuance. The Certificate Body and Certificate Chain will remain accessible and can be copied at any time.

To create a certificate profile, make an API request to the Create Certificate Profile API endpoint.

Sample request

curl --location --request POST 'https://app.kms.hanzo.ai/api/v1/cert-manager/certificate-profiles' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "projectId": "<project-id>",
      "caId": "<ca-id>",
      "certificatePolicyId": "<certificate-policy-id>",
      "slug": "my-api-profile",
      "description": "Certificate profile for API enrollment",
      "enrollmentType": "API",
      "apiConfig": {
          "autoRenew": true,
          "renewBeforeDays": 7
      }
  }'

Sample response

{
  "certificateProfile": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "projectId": "65f0a4b0-c123-4567-8901-23456789abcd",
    "caId": "550e8400-e29b-41d4-a716-446655440000",
    "certificatePolicyId": "660f1234-e29b-41d4-a716-446655440001",
    "slug": "my-api-profile",
    "description": "Certificate profile for API enrollment",
    "enrollmentType": "API",
    "apiConfigId": "770g2345-e29b-41d4-a716-446655440002",
    "createdAt": "2023-01-19T09:44:36.267Z",
    "updatedAt": "2023-01-19T09:44:36.267Z"
  }
}

To issue a certificate against the certificate profile, make an API request to the Issue Certificate API endpoint.

Sample request

curl --location --request POST 'https://app.kms.hanzo.ai/api/v1/cert-manager/certificates' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "profileId": "<certificate-profile-id>",
      "attributes": {
          "commonName": "service.acme.com",
          "ttl": "1y",
          "signatureAlgorithm": "RSA-SHA256",
          "keyAlgorithm": "RSA_2048",
          "keyUsages": ["digital_signature", "key_encipherment"],
          "extendedKeyUsages": ["server_auth"],
          "altNames": [
              {
                  "type": "DNS",
                  "value": "service.acme.com"
              },
              {
                  "type": "DNS",
                  "value": "www.service.acme.com"
              }
          ]
      },
      "metadata": [
          { "key": "env", "value": "production" },
          { "key": "team", "value": "platform" }
      ]
  }'

Sample response

{
  "certificate": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "certificateChain": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "issuingCaCertificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n-----END PRIVATE KEY-----",
    "serialNumber": "123456789012345678",
    "certificateId": "880h3456-e29b-41d4-a716-446655440003"
  },
  "certificateRequestId": "..."
}

Note: If the certificate is available to be issued immediately, the certificate field in the response will contain the certificate data. If issuance is delayed (for example, due to pending approval or additional processing), the certificate field will be null and you can use the certificateRequestId to poll for status or retrieve the certificate when it is ready using the Get Certificate Request API endpoint.

If you have an external private key, you can also issue a certificate by making an API request containing a pem-encoded CSR (Certificate Signing Request) to the same Issue Certificate API endpoint.

Sample request

curl --location --request POST 'https://app.kms.hanzo.ai/api/v1/cert-manager/certificates' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "profileId": "<certificate-profile-id>",
      "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBE9oaW8...\n-----END CERTIFICATE REQUEST-----",
      "attributes": {
          "ttl": "1y"
      }
  }'

Sample response

{
  "certificate": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "certificateChain": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "issuingCaCertificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
    "serialNumber": "123456789012345679",
    "certificateId": "990i4567-e29b-41d4-a716-446655440004"
  },
  "certificateRequestId": "..."
}

Certificate Enrollment via API

On this page