Configure and use REST
The DigiCert® Device Trust Manager REST API makes it easy to automate certificate issuance and management for your IoT devices. You can issue a single certificate or a batch certificate, depending on your needs.
Tip
This topic focuses on how to issue a single certificate using the REST API.
Before you begin
Ensure you've reviewed the following concepts:
Before configuring REST in Device Trust Manager, work with your DigiCert® account representative to:
Set up your DigiCert® ONE account
Configure a Root CA and an Intermediate CA for issuing certificates
Belangrijk
If you're missing any of the above, contact your DigiCert account representative.
Perform the following steps to configure and use REST API:
Sign in to DigiCert ONE as a Solution Administrator:
one.digicert.com (US production)
one.nl.digicert.com (EU production)
demo.one.digicert.com (training, demos, proof of concepts, and pilots)
In DigiCert ONE, in the Manager menu (grid at top right), select Device Trust.
Perform the following steps to configure the REST API:
In the Device Trust Manager menu, select Authentication management > Authentication policies.
Select Create authentication policy and create a new authentication policy.
See Create an authentication policy for a detailed procedure.
Add credentials to your authentication policy.
For this tutorial, just create a passcode and save it — you’ll need it later. See Add passcodes.
Go to Certificate management > Certificate management policies.
Select Create certificate management policy.
See Create a certificate management policy for a detailed procedure.
Enter a Name for the certificate management policy.
Choose a Division to assign the policy to.
Select the required certificate management model.
For this tutorial, we want to implement certificate issuance only (no device management), so select Policy will be used for certificate issuance only. Requires an Essentials license option.
Under Certificate management methods, select Single certificate request through Portal and REST API.
Select the Authentication policy (the one with the passcode) you created.
Select Next to proceed to the certificate settings.
Under Certificate settings:
Select an End entity certificate profile that defines the certificate structure, including subject fields, extensions, and validity period.
Select an Issuing CA from the available options. This is the Certificate Authority that will sign the certificates issued under this policy.
Under Keypair generation settings, select Server-side keypair generation and specify RSA 2048 for the keypair.
You can choose to generate the private key on the device or have it generated on the server-side and sent to the device with the certificate. For this tutorial, we have selected Server-side keypair generation and specified RSA 2048 for the keypair.
Click Next.
Click Finish to complete the certificate management policy.
Obtain the REST endpoint so that you can use it with a REST client. See the full Device Trust Manager REST API Swagger.
Use the following endpoint for single certificate issuance on the DigiCert demo environment:
POST https://demo.one.digicert.com/devicetrustmanager/certificate-issuance-service/api/v2/certificate
You can view the request and response payload options here.
Ensure you update the FQDN based on your instance (for example, one.digicert.com, one.nl.digicert.com, demo.one.digicert.com).
This value (policy ID) is required for the JSON payload.
In the Device Trust Manager menu, select Certificate management > Certificate management policies.
Select the certificate management policy you created above to view its details.
Copy the Certificate management policy ID from the top of the page.
Your Certificate management policy ID will resemble the example below:
IOT_ffab0652-9129-4646-9207-9ac855021e6f
Alternatively, the Device Trust Manager portal UI provides API helpers that assist developers in understanding the REST calls available and the required payload.
Under Certificate management > Certificate management policies, select the certificate management policy you created above to view its details.
Scroll to the API section.
Under the Enroll certificate tab, expand the Individual certificate requests section to view the REST endpoint, Policy ID, and payload example.
You now have everything you need:
REST endpoint
Certificate management policy ID
Authentication passcode
You can use the REST client to request a certificate.
A REST client sends a certificate request and a CSR to Device Trust Manager REST service over a secure HTTPS connection. This request includes the authentication information (for example, passcode) and the CSR, regardless of whether the client or Device Trust Manager is configured to generate the private key.
The following is a sample CURL request with passcode authentication:
curl -X POST https://demo.one.digicert.com/devicetrustmanager/certificate-issuance-service/api/v2/certificate \
-H "Content-Type: application/json" \
-H "x-passcode: YOUR_PASSCODE_HERE" \
-d '{
"certificate_policy_id": "YOUR_POLICY_ID_HERE",
"certificate_profile_attributes": [
{
"id": "subject.common_name",
"value": "Example common name"
}
],
"server_side_key_gen": true,
"key_type": "rsa_2048",
"private_key_format": "pem",
"private_key_syntax": "pkcs8|sec1_or_pkcs1"
}'Optionally, you can also configure certificate-based mutual TLS (mTLS) for added security. Device Trust Manager offers various APIs for device management and certificate issuance, each supporting multiple authentication methods. See Authentication for more information.
When your request is successful, Device Trust Manager returns a signed X.509 certificate. If you selected server-side key generation, the response will also include the private key.
Your response payload will resemble the example below:
{
"certificate_request_id": "1a4e7b7b-03cf-40ff-a93c-41cc0edf220c",
"status": "AUTO_APPROVED",
"result": "SUCCESS",
"certificate_id": "df832ffd-7d5c-4277-99dc-99a1e2b20fc9",
"pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
"ica": "MII..."
}