Skip to main content

Register multiple devices using a batch job

You can use the DigiCert® Device Trust Manager REST API to register multiple devices in a single batch job.

A batch job is ideal when all devices use the same certificate management policy. Instead of sending one request per device, you submit a single request that processes them all at once.

A typical batch registration includes three steps:

  • Choose a key pair generation method

  • Prepare your registration data

  • Start the batch job

Before you begin

To use batch device registration, make sure you have:

  • A certificate policy with BATCH selected as the method.

  • A certificate management policy assigned to an existing device group where the new devices will be registered.

  • The ability to send API requests.

  • API authentication credentials (API key or client certificate).

    Dica

    You can also authenticate with a custom password or an authentication certificate set for the certificate management policy.

Step 1: Choose a key pair generation method

The configuration of your certificate management policy determines which key pair generation methods are available when creating a batch job:

  • Client-side key pair generation

  • Server-side key pair generation

Client-side key pair generation

  • You create the private key and CSR for each device

  • You provide the CSR data when you start the batch job

Server-side key pair generation:

  • Device Trust Manager generates the private key for each device

  • Device Trust Manager encrypts the private key for each registration

Step 2: Prepare your registration data

How you prepare your data to create a batch job for registering multiple devices in Device Trust Manager depends on the key pair method:

Client-side key pair generation

  • You provide a CSR for each device in your batch job request

  • Either upload a ZIP file with individual CSR files or upload a CSV file with CSRs and required fields.

  • The data file (either a CSV or a ZIP) should be added to the data field in the request body’s form-data.

Limits:

  • No limit on the number of devices per job.

  • File size can’t exceed more than 200 MB.

CSV requirements:

Submit a CSV file in the following format:

  • The header row includes a csr column along with columns for each required registration field.

  • Each row beneath the header has details for a single device registration.

  • Use the Device Trust Manager API to download a CSV template with device and certificate fields for a given certificate management policy.

  • After you format the CSV file, upload it as-is or compress it into a ZIP file.

When your CSV file is ready, you can start the batch job and register multiple devices.

Sample: CSV file structure:

The following example shows the CSV format for a batch job to register five devices using client-side key pair generation. For this example, the required certificate fields are:

Common name (subject.common_name)

Organization name (subject.organization_name)

Organization unit (subject.organization_unit)

"device_name","device_description","subject.common_name","subject.organization_name","subject.organization_unit","csr",
"device-01","This a description","DigiCert","IoT","example-01.com","-----BEGIN CERTIFICATE REQUEST-----MIICYz...-----END CERTIFICATE REQUEST-----",
"device-02","This a description","DigiCert","IoT","example-02.com","-----BEGIN CERTIFICATE REQUEST-----MIICYz...-----END CERTIFICATE REQUEST-----",
"device-03","This a description","DigiCert","IoT","example-03.com","-----BEGIN CERTIFICATE REQUEST-----MIICYz...-----END CERTIFICATE REQUEST-----",
"device-04","This a description","DigiCert","IoT","example-04.com","-----BEGIN CERTIFICATE REQUEST-----MIICYz...-----END CERTIFICATE REQUEST-----",
"device-05","This a description","DigiCert","IoT","example-05.com","-----BEGIN CERTIFICATE REQUEST-----MIICYz...-----END CERTIFICATE REQUEST-----"

Sample: Key pair generation with CSV

Submit a POST request to the following API endpoint:

{{base_url}}/devicetrustmanager/certificate-batch-service/api/v1/jobs

POST request instructions:

Follow these to format your request:

  • Request URL: Replace {{base_url}} with the base URL for your DigiCert ONE instance. For example, https://one.digicert.com

  • Certificate management policy ID: In the request body (form-data), set the certificate management policy ID to an existing entry from the DigiCert ONE platform

    You can either copy the ID from the certificate management policy details page or retrieve it using the API.

  • Headers:

    • Set the Content-Type header to multipart/form-data

    • Include authentication credentials for your selected authentication method

  • API token:

    • Add the custom header x-api-key

    • The API token must belong to the user or service user creating the batch job.

  • Authentication certificate:

    • Prefix the hostname in the request URL with clientauth. For example, https://clientauth.one.digicert.com

    • Present a trusted authentication certificate when submitting the request.

  • Request body:

    • Provide the device registration data in a CSV format.

    • The CSV file must include a column named csr that contains the CSR for each device to be registered.

  • Response:

    A successful request returns:

    • Status code: 200 OK

    • The ID of the newly created batch job.

    Sample: Requests and responses

    Create a batch job for device registration:

    curl --location 'https://int.devicetm.dev.blu.digicert.com/devicetrustmanager/certificate-batch-service/api-ui/v1/jobs?job_type=device_registration' \
--header 'x-api-key: xxxxxxxxx' \
--form 'name="Batch-Device-01"' \
--form 'device_group_id="xxxxxxxxxx-xxxxxxxx-xxxxxxxx"' \
--form 'certificate_policy_id="IOT_xxxxxxxxxx"' \
--form 'server_side_key_gen="false"' \
--form 'key_type="RSA_2048"' \
--form 'passcode="1234"' \
--form 'emails="info@digicert.com"' \
--form 'external_emails="info@digicert.com"' \
--form 'passcode_generation_option="true"' \
--form 'data=@"/data.csv"'

Server-side key pair generation

  • You provide information about each device in the batch job in a CSV file

  • Upload the compressed CSV file

  • Include a PEM-encoded authentication certificate or a PGP public key to encrypt the private keys and issued certificates

  • Submit the certificate using the encryption_certificate field in the body of your request to start the batch job

Limits:

  • No limit on devices per job.

  • File size can’t exceed more than 200 MB.

CSV requirements:

Submit a CSV file in the following format:

  • The header row includes a column for each required device registration field.

  • Use Device Trust Manager API to download a CSV template with certificate fields for your certificate management policy.

  • Each row beneath the header has details for a single device registration.

  • After you format the CSV file, upload it as-is or compress it into a ZIP file.

When your CSV file is ready, you can start the batch job.

Sample: CSV file structure:

The following example shows the CSV format for a batch job to register five devices. For this example, the required device fields are:

  • Common name (subject.common_name)

  • Organization name (subject.organization_name)

    "subject.common_name","subject.organization_name","subject.organization_unit","san.dns_name"
"Example01","DigiCert","IoT","example-01.com"
"Example02","DigiCert","IoT","example-02.com"
"Example03","DigiCert","IoT","example-03.com"
"Example04","DigiCert","IoT","example-04.com"
"Example05","DigiCert","IoT","example-05.com"

Sample: Key pair generation with CSV

Submit a POST request to the following API endpoint:

{{base_url}}/devicetrustmanager/certificate-batch-service/api/v1/jobs

POST request instructions:

  • Request URL: Replace {{base_url}} with the base URL for your DigiCert ONE instance. For example, https://one.digicert.com

  • Certificate management policy ID: In the request body (form-data), set the certificate management policy ID to an existing entry from the DigiCert ONEplatform

    You can either copy the ID from the certificate management policy details page or retrieve it using the API.

    Headers:

    • Set the Content-Type header to multipart/form-data

    • Include authentication credentials for your selected authentication method

    API token:

    • Add the custom header x-api-key

    • The API token must belong to the user or service user creating the batch job.

    Authentication certificate:

    • Prefix the hostname in the request URL with clientauth. For example, https://clientauth.one.digicert.com

    • Present a trusted authentication certificate when submitting the request.

    Request body:

    • Provide the device registration data in CSV format.

    • The CSV file must include a column named csr that contains the CSR for each device to be registered.

    Response: A successful request returns:

    • Status code: 200 OK

    • The ID of the newly created batch job.

    Sample: Requests and responses:

    Create a batch job for device registration:

    curl --location 'https://int.devicetm.dev.blu.digicert.com/devicetrustmanager/certificate-batch-service/api-ui/v1/jobs?job_type=device_registration' \
--header 'x-api-key: xxxxxxxxx' \
--form 'name="Batch-Device-01"' \
--form 'device_group_id="xxxxxxxxxx-xxxxxxxx-xxxxxxxx"' \
--form 'certificate_policy_id="IOT_xxxxxxxxxx"' \
--form 'server_side_key_gen="true"' \
--form 'key_type="RSA_2048"' \
--form 'passcode="1234"' \
--form 'emails="info@digicert.com"' \
--form 'external_emails="info@digicert.com"' \
--form 'passcode_generation_option="true"' \
--form 'encryption_certificate="------BEGIN CERTIFICATE-----"' \
--form 'data=@"/data.csv"'

Step 3: Start the batch job

Make sure you prepare your registration data according to the requirements of the key pair generation method you want to use.

Submit a POST request to the correct API endpoint associated with your key pair method.

Common request parameters

The endpoint path, request body structure, and required parameters vary depending on your chosen key pair generation method.

The following table details some of the parameters used in requests to start a batch job:

Tabela 1. Common request parameters

Name

Required/Optional

Type

Description

job_type

Required

String

Specifies the type of the job.

Allowed value: device_registration.

name

Required

String

Name of the batch job.

device_group_id

Required

String

Specifies the relevant device for linking each new registered device.

certificate_policy_id

Optional

String

The corresponding certificate management policy for registering new devices.

server_side_key_gen

Required

Boolean

Allowed values:

  • true: Represents server-side keygen.

  • false: Represents client-side keygen.

key_type

Optional

String

Supported keygen types based on certificate management policy configuration.

Allowed values:

  • RSA_1024.

  • RSA_2048.

  • RSA_3072.

  • RSA_4096.

  • P_256.

  • P_384.

  • P_521.

  • ED_25519.

  • DAIMLER_ED_25519.

  • DILITHIUM_2.

  • DILITHIUM_3.

  • DILITHIUM_5.

encryption_certificate

Required - server side keygen only

Text

Example value:

-----BEGIN CERTIFICATE--MIIFAzCCA+ugA....

data

Required

Allowed file extensions:

  • csv

  • zip

Data file

Represents a list of devices to be registered.

Example value: data.csv.

emails

Optional

String

Example value: info@digicert.com

external_emails

Optional

String

Example value: info@digicert.com

passcode_generation_option

Optional

Only applicable to external users

String

Example values:

  • none

  • generated: system generated passode.

  • provided: user provided passcode

passcode

Required

Only applicable where the passcode generation option is provided

String

Example value:

1234567


Step 4: Check the batch job status

Device 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 check the status of the batch jobs, submit a GET request to the following endpoint:

{{base_url}}/devicetrustmanager/certificate-batch-service/api/v1/jobs{{job_id}}

In the request URL:

  • Replace the base_url with the base URL of your DigiCert ONE instance. For example, https://one.digicert.com

  • Replace the {{job_id}} with the batch job ID returned when you created the batch job.

Statuses:

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

  • PENDING_APPROVAL - Needs approval before Device Trust Manager processes the enrollments.

  • IN_PROGRESS - Jobs are currently being processed.

  • COMPLETE - Finished and ready to download.

Sample: Request and response

Get batch job details:

curl 'https://one.digicert.com/devicetrustmanager/certificate-batch-service/api/v1/jobs/7a984652-8f38-412a-8c37-74569e3e8e7c' \
--header 'X-API-KEY: {{api-key}}' \

Download the Batch Job Report

You can download the batch job report once the status is either COMPLETE or FAILED.

To download a batch job report, submit a GET request to the following endpoint:

{{base_url}}/devicetrustmanager/certificate-batch-service/api/v1/jobs{{job_id}}/download/report
Nesta secção: