Start the batch job

This section includes instructions and examples to help you format your API request to start a batch enrollment job in DigiCert® IoT Trust Manager.

Before you begin, make sure to prepare your enrollment data according to the requirements of the keypair generation method you want to use. Then, to start the batch job, submit a POST request to the API endpoint associated with your chosen keypair generation method.

Get example API requests from DigiCert® IoT Trust Manager

You can copy example cURL requests that show the syntax for creating batch jobs with an enrollment profile from your DigiCert® IoT Trust Manager account:

Sign in to DigiCert ONE.
In DigiCert® IoT Trust Manager, open the enrollment profile details page for the enrollment profile you are using for your batch job.
In the API section, under Batch certificate requests, select your keypair generation method.
Copy the cURL example to your clipboard.

Request parameters

This section describes some of the parameters used in requests to start a batch job. The endpoint path, request body structure, and required parameters vary depending on your chosen keypair generation method. For example payloads for each method, visit the sections below:

Tip

For a complete list of request parameters and their meanings, see the API reference: Batch enrollment jobs.

Name	Req/Opt	Type	Description
`certificate_format`	required	string	File format of certificate output. Allowed values: `pem`: Certificates will be delivered in PEM format. `der`: Certificates will be delivered in DER format. `json`: Response will be provided in JSON format. `smpb`: Response will be provided in MPKI-8 compatible format.
`include_full_chain_with_each_certificate`	optional	bool	If `true`, the batch job delivers the issuing intermediate and root CA certificates for each end-entity certificate. If `false`, the batch job delivers only the end-entity certificates.
`include_intermediates_with_each_certificate`	optional	bool	If `true`, the batch job delivers the issuing intermediate CA certificates for each end-entity certificate. If `false`, the batch job delivers only the end-entity certificates.
`report_format`	optional	string	Batch job report format. Allowed values: `csv` `json`
`private_key_format`	optional	string	For batch jobs using server-side keypair generation, the format of the returned private keys. `pem`: Returns the private keys in PEM format. `der`: Returns the private keys in DER format.
`private_key_syntax`	optional	string	For batch jobs using server-side keypair generation, the syntax of the returned private keys. `pkcs8`: PKCS8 `sec1_or_pkcs1`: SEC1 (for ECDSA keys) or PKCS1 (for RSA keys).

Client-side keypair generation

To create a batch enrollment job using client-side keypair generation, submit a POST request to the following API endpoint:

{{base_url}}/iot/api/v1/enrollment-profile/{{enrollment_profile_id}}/batch-enroll

Format your request as follows:

In the request URL:
- Replace {{base_url}} with the base URL for your instance of DigiCert ONE (for example, https://one.digicert.com).
- Replace {{enrollment_profile_id}} with the ID of your enrollment profile. You can copy the enrollment profile ID from the enrollment profile details page, or retrieve it from the API (see List enrollment profiles).
Set the value of the Content-Type header to multipart/form-data.
Include authentication credentials for your chosen authentication method.
- API token
  Include the custom header x-api-key with the API token belonging to the user or service user creating the batch job.
- Passcode
  Include the custom header passcode containing a valid passcode for authenticating to the enrollment profile.
- Authentication certificate
  In the request URL, prefix the hostname with clientauth (for example, https://clientauth.one.digicert.com). Present a trusted authentication certificate when you submit your request.
In the request body, provide your enrollment data. See enrollment data requirements for client-side keypair generation.

A successful request returns a response status code of 200 OK. The response includes the ID of the newly created batch job. Store this ID, as you need it to complete the batch enrollment flow.

Example requests and responses

Example 2. 200 OK

{
    "id": "6a41042d-6168-4417-85e8-1ef1caeb5e27",
    "name": "Example batch job",
    "status": "PENDING",
    "total_items": 5,
    "failed_items": 0,
    "processing_time": 0,
    "job_type": "BATCH_CERTIFICATE_ENROLL",
    "requested_by_name": "john.doe",
    "passcode_generation_option": "NONE",
    "certificate_format": "json",
    "emails": [
        "john.doe@example.com"
    ],
    "include_full_chain_with_each_certificate": false,
    "include_intermediates_with_each_certificate": false
}

Server-side keypair generation: CSV

To use a CSV file to create a batch enrollment job using server-side keypair generation, submit a POST request to the following API endpoint:

{{base_url}}/iot/api/v1/enrollment-profile/{{enrollment_profile_id}}/batch-enroll-key-gen

Format your request as follows:

In the request URL:
- Replace {{base_url}} with the base URL for your instance of DigiCert ONE (for example, https://one.digicert.com).
- Replace {{enrollment_profile_id}} with the ID of your enrollment profile. You can copy the enrollment profile ID from the enrollment profile details page, or retrieve it from the API (see List enrollment profiles).
Set the value of the Content-Type header to multipart/form-data.
Include authentication credentials for your chosen authentication method.
- API token
  Include the custom header x-api-key with the API token belonging to the user or service user creating the batch job.
- Passcode
  Include the custom header passcode containing a valid passcode for authenticating to the enrollment profile.
- Authentication certificate
  In the request URL, prefix the hostname with clientauth (for example, https://clientauth.one.digicert.com). Present a trusted authentication certificate when you submit your request.
In the request body, provide your enrollment data and a certificate or PGP public key to encrypt the issued certificates. See CSV requirements for server-side keypair generation.

A successful request returns a response status code of 200 OK. The response includes the ID of the newly created batch job. Store this ID, as you need it to complete the batch enrollment flow.

Example requests and responses

Example 3. Encrypt with certificate

curl 'https://one.digicert.com/iot/api/v1/enrollment-profile/IOT_7919eed6-688b-4471-a9e7-e484f2b883f9/batch-enroll-key-gen' \
--header 'X-API-KEY: {{api-key}}' \
--header 'Content-Type: multipart/form-data' \
--form 'name="test_job"' \
--form 'certificate_format="json"' \
--form 'data=@"<your_csv_file>.zip"' \
--form 'emails="john.doe@example.com"' \
--form 'key_type="rsa_2048"' \
--form 'signature_algorithm="match_issuer"' \
--form 'certificate="-----BEGIN CERTIFICATE-----MIIEYz...Qv06XY=-----END CERTIFICATE-----"'

Example 4. Encrypt with PGP public key

curl 'https://one.digicert.com/iot/api/v1/enrollment-profile/IOT_7919eed6-688b-4471-a9e7-e484f2b883f9/batch-enroll-key-gen' \
--header 'X-API-KEY: {{api-key}}' \
--header 'Content-Type: multipart/form-data' \
--form 'name="test_job"' \
--form 'certificate_format="json"' \
--form 'data=@"<your_csv_file>.zip"' \
--form 'emails="john.doe@example.com"' \
--form 'key_type="rsa_2048"' \
--form 'signature_algorithm="match_issuer"' \
--form 'certificate="-----BEGIN PGP PUBLIC KEY BLOCK-----mQINB...Ww===QOmE-----END PGP PUBLIC KEY BLOCK-----"'

Example 5. 200 OK

 {
    "id": "6a41042d-6168-4417-85e8-1ef1caeb5e27",
    "name": "Example batch job",
    "status": "PENDING",
    "total_items": 5,
    "failed_items": 0,
    "processing_time": 0,
    "job_type": "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN",
    "requested_by_name": "john.doe",
    "passcode_generation_option": "NONE",
    "certificate_format": "json",
    "emails": [
        "john.doe@example.com"
    ],
    "include_full_chain_with_each_certificate": false,
    "include_intermediates_with_each_certificate": false
}

Server-side keypair generation: MAC addresses

To use MAC addresses to create a batch enrollment job using server-side keypair generation, submit a POST request to the following API endpoint:

{{base_url}}/iot/api/v1/enrollment-profile/{{enrollment_profile_id}}/batch-enroll-key-gen-mac

Format your request as follows:

In the request URL:
- Replace {{base_url}} with the base URL for your instance of DigiCert ONE (for example, https://one.digicert.com).
- Replace {{enrollment_profile_id}} with the ID of your enrollment profile. You can copy the enrollment profile ID from the enrollment profile details page, or retrieve it from the API (see List enrollment profiles).
Set the value of the Content-Type header to multipart/form-data.
Include authentication credentials for your chosen authentication method.
- API token
  Include the custom header x-api-key with the API token belonging to the user or service user creating the batch job.
- Passcode
  Include the custom header passcode containing a valid passcode for authenticating to the enrollment profile.
- Authentication certificate
  In the request URL, prefix the hostname with clientauth (for example, https://clientauth.one.digicert.com). Present a trusted authentication certificate when you submit your request.
In the request body, provide your enrollment data and a certificate or PGP public key to encrypt the issued certificates. See MAC address requirements for server-side keypair generation.

A successful request returns a response status code of 200 OK. The response includes the ID of the newly created batch job. Store this ID, as you need it to complete the batch enrollment flow.

Example requests and responses

Example 6. Encrypt with certificate

curl 'https://one.digicert.com/iot/api/v1/enrollment-profile/IOT_7919eed6-688b-4471-a9e7-e484f2b883f9/batch-enroll-key-gen-mac' \
--header 'X-API-KEY: {{api-key}}' \
--header 'Content-Type: multipart/form-data' \
--form 'name="test_job"' \
--form 'certificate_format="json"' \
--form 'mac_address_from="00:1a:c2:7b:00"' \
--form 'mac_address_number="5"' \
--form 'mac_address_step="10"' \
--form 'emails="john.doe@example.com"' \
--form 'key_type="rsa_2048"' \
--form 'certificate="-----BEGIN CERTIFICATE-----MIIEYz...Qv06XY=-----END CERTIFICATE-----"'

Example 7. Encrypt with PGP public key

curl 'https://one.digicert.com/iot/api/v1/enrollment-profile/IOT_7919eed6-688b-4471-a9e7-e484f2b883f9/batch-enroll-key-gen-mac' \
--header 'X-API-KEY: {{api-key}}' \
--header 'Content-Type: multipart/form-data' \
--form 'name="test_job"' \
--form 'certificate_format="json"' \
--form 'mac_address_from="00:1a:c2:7b:00"' \
--form 'mac_address_number="5"' \
--form 'mac_address_step="10"' \
--form 'emails="john.doe@example.com"' \
--form 'key_type="rsa_2048"' \
--form 'certificate="-----BEGIN PGP PUBLIC KEY BLOCK-----mQINB...Ww===QOmE-----END PGP PUBLIC KEY BLOCK-----"'

Example 8. 200 OK

{
    "id": "6a41042d-6168-4417-85e8-1ef1caeb5e27",
    "name": "Example batch job",
    "status": "PENDING",
    "total_items": 5,
    "failed_items": 0,
    "processing_time": 0,
    "job_type": "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN_MAC",
    "requested_by_name": "john.doe",
    "passcode_generation_option": "NONE",
    "certificate_format": "json",
    "emails": [
        "john.doe@example.com"
    ],
    "include_full_chain_with_each_certificate": false,
    "include_intermediates_with_each_certificate": false
}

Check batch job status

DigiCert® IoT Trust Manager processes batch jobs in the order they are received. After submitting a request to start a batch job, you can track its progress by using the API to poll batch job status.

To get the status of a batch job, submit a GET request to the following endpoint:

{{base_url}}/iot/api/v1/batch-enroll/{{job_id}}

Tip

For detailed information about this endpoint, see the API reference: Batch job details.

In the request URL:

Replace base_url with the base URL of your DigiCert ONE instance (for example, https://one.digicert.com).
Replace {{job_id}} with the batch job ID returned when you created the batch job.

This endpoint returns a status field with the current batch job status.

Jobs that are PENDING_APPROVAL must be approved before DigiCert® IoT Trust Manager processes the enrollments.
Jobs that are IN_PROGRESS are currently processing.
Jobs that are COMPLETE are ready to download.

Example request and response

Example 10. 200 OK

{
    "id": "7a984652-8f38-412a-8c37-74569e3e8e7c",
    "name": "Example batch job",
    "status": "IN_PROGRESS",
    "total_items": 5,
    "failed_items": 0,
    "processing_time": 0,
    "job_type": "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN",
    "requested_by_name": "john.doe",
    "passcode_generation_option": "NONE",
    "certificate_format": "json",
    "emails": [
        "john.doe@example.com"
    ],
    "include_full_chain_with_each_certificate": false,
    "include_intermediates_with_each_certificate": false
}

What's next?

After you submit a request to start a batch enrollment job, the next step depends on whether the enrollment profile requires certificate approvals.

When approvals are required

If the enrollment profile requires certificate approvals, a user with the right permissions must approve the batch job before DigiCert® IoT Trust Manager processes the enrollments in your request.

After receiving your request to start a batch job, DigiCert® IoT Trust Manager sends notifications to the approvers listed in the enrollment profile's configuration. To approve or reject the batch job, approvers can follow the instructions in the approval notification. Alternatively, if you want to manage approvals using the API, see manage batch job approvals.

When requests are auto-approved

If the enrollment profile auto-approves certificate requests, DigiCert® IoT Trust Manager immediately approves the job and queues it for processing. When processing begins, the status of the batch job changes from APPROVED to IN_PROGRESS. When the batch job status is COMPLETE, you can download the certificates.

In this section:

Start the batch job

Get example API requests from DigiCert​​®​​ IoT Trust Manager

Request parameters

Tip

Client-side keypair generation

Example requests and responses

Server-side keypair generation: CSV

Example requests and responses

Server-side keypair generation: MAC addresses

Example requests and responses

Check batch job status

Tip

Example request and response

What's next?

When approvals are required

When requests are auto-approved

Search results

Get example API requests from DigiCert® IoT Trust Manager