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).
Tipp
You can also authenticate with a custom password or an authentication certificate set for the certificate management policy.
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
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 tomultipart/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 tomultipart/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"'
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:
Name | Required/Optional | Type | Description |
---|---|---|---|
job_type | Required | String | Specifies the type of the job. Allowed value: |
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:
|
key_type | Optional | String | Supported keygen types based on certificate management policy configuration. Allowed values:
|
encryption_certificate | Required - server side keygen only | Text | Example value: -----BEGIN CERTIFICATE--MIIFAzCCA+ugA.... |
data | Required Allowed file extensions:
| Data file | Represents a list of devices to be registered. Example value: |
emails | Optional | String | Example value: |
external_emails | Optional | String | Example value: |
passcode_generation_option | Optional Only applicable to external users | String | Example values:
|
passcode | Required Only applicable where the passcode generation option is | String | Example value:
|
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