{ "openapi": "3.0.3", "info": { "title": "DigiCert® IoT Trust Manager REST API", "description": "\nDownload the OpenAPI definition for this page:\n- [YAML format](/api-reference/openapi/iot-trust.yaml)\n- [JSON format](/api-reference/openapi/iot-trust.json)\n\nThe DigiCert® IoT Trust Manager API provides a powerful interface for customizing and automating workflows for your certificates and devices.\n\nThe base path for all endpoints is: `{server}/iot/api/`. See the `securitySchemes` section (or click the **Authorize** button) for available auth methods.\n\nAll requests are submitted via RESTful URLs using REST features, including header-based authentication and JSON request types. The data character set encoding for requests is UTF-8. A well-formed request uses port 443 and specifies the user-agent and content-length HTTP headers.\n\n## Authentication\n\nThe DigiCert® IoT Trust Manager APIs support header-based API key authentication. Additionally, a subset of the DigiCert® IoT Trust Manager APIs support authentication using an enrollment passcode or client certificate.\n\n### API key authentication\n\nTo authenticate with an API key, include the custom HTTP header `x‑api‑key` in your request. Provide your own API key as the value for this header when you submit your request.\n\nTo create a new API key:\n\n1. Sign in to DigiCert ONE.\n2. Navigate to the **Account Manager** console.\n3. From the left menu, select **Access > Administrators**.\n4. Find your information in the Administrators list, and select your name to open the Administrator details page.\n5. From the Administrator details page, in the API Tokens section, select **Create API token**.\n6. Fill out the form to create the key.\n7. Copy it. Remember to stash the API key in a safe location. Delete it when you no longer need it.\n\n**Note:** Each API key is only displayed once. There is no way to retrieve a lost API key. If you ever lose an API key, revoke it and generate a new one.\n\n### Enrollment passcode authentication\n\nThe following endpoints in the DigiCert® IoT Trust Manager API support the option to authenticate with an enrollment passcode instead of an API key:\n\n* Request certificate\n* Renew certificate\n\nTo authenticate with an enrollment passcode, use the custom HTTP header `x-passcode`. The value of the `x-passcode` header is the passcode associated with the enrollment profile you specify in the body of the request. Requests that use enrollment passcode authentication do not include the `x-api-key` header.\n\n### Client certificate authentication\n\nMany endpoints in the DigiCert® IoT Trust Manager API support the option for mutual TLS authentication. With mutual TLS authentication, a client can access the endpoint by presenting a trusted certificate in the request.\n\nTo use mutual TLS authentication:\n\n* Include a trusted certificate in your request.\n* In the base URL for the endpoint path, add the prefix `clientauth`. For example: `https://clientauth.one.digicert.com`\n* Omit the `x-api-key` header.\n\n**Supported endpoints**\n\nClients can authenticate to the following endpoints by presenting a certificate associated with the device:\n\n* Get device details by ID (client authentication)\n* Update device by ID (client authentication)\n* Renew device certificate by device ID (client authentication)\n\nClients can authenticate to the following endpoints by presenting a certificate that is registered to the enrollment profile specified in the request payload:\n\n* Request certificate\n* Renew certificate\n", "version": "1.0.0" }, "tags": [ { "name": "Certificates", "description": "Manage certificate lifecycles for your IoT devices" }, { "name": "Authentication CA certificates", "description": "Manage authentication CA certificates" }, { "name": "Authentication CA templates", "description": "Manage authentication CA certificate templates" }, { "name": "Authentication certificates", "description": "Manage authentication certificates for enrollment profiles" }, { "name": "Certificate profiles", "description": "Manage certificate profiles" }, { "name": "Certificate requests", "description": "View certificate requests" }, { "name": "Certificate templates", "description": "Manage certificate templates" }, { "name": "Devices", "description": "Create and manage devices" }, { "name": "Devices (v2)", "description": "Create and manage devices without using a device name" }, { "name": "Devices (v3)", "description": "Get and update device record, renew, revoke and fetch device certificates" }, { "name": "Divisions", "description": "Create and manage divisions in your DigiCert® IoT Trust Manager account" }, { "name": "Enrollment profiles", "description": "Manage enrollment profiles" }, { "name": "Enrollment profile passcodes", "description": "Manage enrollment profile passcodes" }, { "name": "Audit logs", "description": "Get information about activity in your DigiCert® IoT Trust Manager account" }, { "name": "ACME", "description": "Add ACME authentication credentials to your account" }, { "name": "Batch certificate enrollment", "description": "Manage batch certificate enrollment jobs" }, { "name": "External batch certificate enrollment", "description": "Request certificates from another DigiCert ONE account" }, { "name": "Device profiles", "description": "Create device profiles" }, { "name": "ICAs", "description": "View details about ICAs used in DigiCert® IoT Trust Manager" }, { "name": "Gateways", "description": "View and manage gateways. A gateway is an application that runs on a host server on your network. Gateways can route requests from devices without internet connectivity to DigiCert® IoT Trust Manager." }, { "name": "OCSP groups", "description": "View and manage Online Certificate Status Protocol (OCSP) groups. With OCSP groups, you can get the status of every certificate in the group by making a single OCSP request for any certificate in the group." }, { "name": "Trust bundles", "description": "View and manage certificates trust bundles." } ], "security": [ { "ApiKeyAuth": [] } ], "servers": [ { "url": "{server}/iot/api", "variables": { "server": { "default": "https://one.digicert.com" } } } ], "paths": { "/v1/audit-log": { "get": { "tags": [ "Audit logs" ], "description": "Use this endpoint to get audit log records for your DigiCert® IoT Trust Manager account.\n", "operationId": "getAuditLogs", "summary": "Get audit log records", "parameters": [ { "in": "query", "name": "account_id", "description": "Filters results by account ID.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "divisions", "description": "Comma-separated list of division IDs. Limits results to the divisions in the list you provide.", "schema": { "type": "string", "example": "51efe603-9514-41a5-b7dc-d2922cc98b66,ee64ec0f-510f-4565-296e-2d5fe925690f" } }, { "in": "query", "name": "authentication_type", "description": "The authentication type associated with the event.\n- `user` - For events that were authenticated with user credentials or a DigiCert ONE API key.\n- `passcode` - For events that were authenticated with an enrollment passcode.\n- `certificate` -For events that were authenticated with an existing certificate (for example, during a renewal request).\n- `authentication_ca` - For events that were authenticated with an authentication certificate authority (CA).\n- `authentication_certificate` - For events that were authenticated with an authentication certificate.\n", "schema": { "$ref": "#/components/schemas/authentication_type" } }, { "in": "query", "name": "authentication_id", "description": "Filters results by the ID of the authentication object associated with the record. This can be the ID of a user, passcode, certificate, authentication certificate authority (CA), or authentication certificate.", "schema": { "type": "string", "example": "89101e8f-9557-4391-bd33-219f8f62157d" } }, { "in": "query", "name": "resource_type", "description": "Filters results by resource type.", "schema": { "$ref": "#/components/schemas/resource_type" } }, { "in": "query", "name": "resource_name", "description": "Filters results by resource name.", "schema": { "type": "string", "example": "Resource name" } }, { "in": "query", "name": "resource", "description": "Filters results by resource ID.", "schema": { "type": "string", "example": "Resource ID" } }, { "in": "query", "name": "action", "description": "Filters results by action.", "schema": { "$ref": "#/components/schemas/action" } }, { "in": "query", "name": "statuses", "description": "Comma-separated list of statuses. Limits results to the statuses in the list you provide. *Available values*: success, failed\n", "schema": { "type": "string", "example": "success" } }, { "in": "query", "name": "created_at_from", "description": "Limits results to records created **after** a specific date and time (UTC).\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "created_at_to", "description": "Limits results to records created **before** a specific date and time (UTC).\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "$ref": "#/components/parameters/pagination" }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `created_at` property.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 1000, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "Array of audit log records. Each audit log record is an object with key/value pairs that provide information about an event in your DigiCert® IoT Trust Manager account.", "items": { "oneOf": [ { "$ref": "#/components/schemas/failedRequestDetails" }, { "$ref": "#/components/schemas/successfulRequestDetails" } ] } } } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `VIEW_IOT_AUDIT_LOG` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/authentication-ca": { "get": { "summary": "List authentication CA certificates", "operationId": "listAuthenticationCACertificates", "tags": [ "Authentication CA certificates" ], "description": "Use this endpoint to get a list of authentication CA certificates.\n", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to authentication CA certificates for the given account.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "name", "description": "Limits results to authentication CA certificates with a name that contains the given string.\n", "schema": { "type": "string", "example": "Authentication CA certificate name" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to authentication CA certificates used in the given enrollment profile (UUID).\n", "schema": { "type": "string", "format": "uuid", "example": "a21cc3b4-4ee7-4d50-ab0c-484633804217" } }, { "in": "query", "name": "enrollment_profile_name", "description": "Limits results to authentication CA certificates used in an enrollment profile with the given name.\n", "schema": { "type": "string", "example": "Example enrollment profile" } }, { "in": "query", "name": "enrollment_profile_name", "description": "Limits results to authentication CA certificates used in an enrollment profile with the given name.\n", "schema": { "type": "string", "example": "Example enrollment profile" } }, { "in": "query", "name": "created_from", "description": "Limits results to authentication CA certificates created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to authentication CA certificates created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "valid_from_start", "description": "Limits results to authentication CA certificates with a `valid_from` value on or after the given date or date-time. Use with `valid_from_end` to search for authentication CAs with a `valid_from` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_from_end", "description": "Limits results to authentication CA certificates with a `valid_from` value on or before the given date or date-time. Use with `valid_from_start` to search for authentication CAs with a `valid_from` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_to_start", "description": "Limits results to authentication CA certificates with a `valid_to` value on or after the given date or date-time. Use with `valid_to_end` to search for authentication CAs with a `valid_to` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "format": "date-time", "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_to_end", "description": "Limits results to authentication CA certificates with a `valid_to` value on or before the given date or date-time. Use with `valid_to_start` to search for authentication CAs with a `valid_to` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\nformat: date-time\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "status", "description": "Limits results to authentication CA certificates with the given status. By default, deleted authentication CA certificates do not appear in the results. To search for deleted authentication CAs, use `status=DELETED`.\n", "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. If not provided, results are sorted in descending order by date created (`created_at`).\n", "schema": { "type": "string", "enum": [ "created_at", "id", "thumbprint", "valid_from", "valid_to", "status" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20, "example": 1 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with authentication CA certificate details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List authentication CA certificates.", "items": { "$ref": "#/components/schemas/authenticationCACertificateResponse" } } } } } } } } } }, "/v1/account/{account_id}/authentication-ca": { "get": { "summary": "List authentication CA certificates by account", "operationId": "listAuthenticationCACertificatesByAccount", "tags": [ "Authentication CA certificates" ], "deprecated": true, "description": "Use this endpoint to get a list of authentication CA certificates for the given account.\n\nThis endpoint is deprecated. Use [List authentication CA certificates](#/Authentication%20CA%20certificates/listAuthenticationCACertificates). \n", "parameters": [ { "in": "path", "name": "account_id", "required": true, "description": "Account ID.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "name", "description": "Limits results to authentication CA certificates with a name that contains the given string.\n", "schema": { "type": "string", "example": "Authentication CA certificate name" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to authentication CA certificates used in the given enrollment profile (UUID).\n", "schema": { "type": "string", "format": "uuid", "example": "a21cc3b4-4ee7-4d50-ab0c-484633804217" } }, { "in": "query", "name": "enrollment_profile_name", "description": "Limits results to authentication CA certificates used in an enrollment profile with the given name.\n", "schema": { "type": "string", "example": "Example enrollment profile" } }, { "in": "query", "name": "enrollment_profile_name", "description": "Limits results to authentication CA certificates used in an enrollment profile with the given name.\n", "schema": { "type": "string", "example": "Example enrollment profile" } }, { "in": "query", "name": "created_from", "description": "Limits results to authentication CA certificates created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to authentication CA certificates created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "valid_from_start", "description": "Limits results to authentication CA certificates with a `valid_from` value on or after the given date or date-time. Use with `valid_from_end` to search for authentication CAs with a `valid_from` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_from_end", "description": "Limits results to authentication CA certificates with a `valid_from` value on or before the given date or date-time. Use with `valid_from_start` to search for authentication CAs with a `valid_from` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_to_start", "description": "Limits results to authentication CA certificates with a `valid_to` value on or after the given date or date-time. Use with `valid_to_end` to search for authentication CAs with a `valid_to` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "format": "date-time", "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_to_end", "description": "Limits results to authentication CA certificates with a `valid_to` value on or before the given date or date-time. Use with `valid_to_start` to search for authentication CAs with a `valid_to` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\nformat: date-time\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "status", "description": "Limits results to authentication CA certificates with the given status. By default, deleted authentication CA certificates do not appear in the results. To search for deleted authentication CAs, use `status=DELETED`.\n", "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. If not provided, results are sorted in descending order by date created (`created_at`).\n", "schema": { "type": "string", "enum": [ "created_at", "id", "thumbprint", "valid_from", "valid_to", "status" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20, "example": 1 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with authentication CA certificate details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of objects with authentication CA certificate details.", "items": { "$ref": "#/components/schemas/authenticationCACertificateResponse" } } } } } } } } }, "post": { "summary": "Upload authentication CA certificate", "tags": [ "Authentication CA certificates" ], "operationId": "uploadAuthenticationCACertificate", "description": "Use this endpoint to upload an authentication CA certificate to your DigiCert® IoT Trust Manager account. The request uses a content type of multipart/form-data. The body of the request is the CA certificate formatted as a PEM file.\n", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Object with authentication CA certificate details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCACertificateResponse" } } } } } } }, "/v1/account/{account_id}/authentication-ca/{authentication_ca_id}": { "get": { "tags": [ "Authentication CA certificates" ], "summary": "Get authentication CA certificate", "operationId": "getAuthenticationCACertificate", "description": "Use this endpoint to get information about the given authentication CA certificate.\n", "parameters": [ { "in": "path", "name": "account_id", "required": true, "description": "Account ID.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "path", "name": "authentication_certificate_id", "required": true, "description": "Authentication CA certificate ID (UUID).", "schema": { "type": "string", "format": "uuid", "example": "0ee10bb3-76c0-4430-8436-6696b52ffa22" } } ], "responses": { "200": { "description": "Object with authentication CA certificate details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCACertificateResponse" } } } } } } }, "/v1/account/{account_id}/authentication-ca/{authentication_ca_id}/delete": { "put": { "tags": [ "Authentication CA certificates" ], "summary": "Delete authentication CA certificate", "operationId": "deleteAuthenticationCACertificate", "description": "Use this endpoint to delete an authentication CA certificate from an account. You cannot use a deleted authentication CA certificate to create new authentication certificates in DigiCert® IoT Trust Manager.\n\nAdditionally, deleted authentication CA certificates do not appear in search results on the **List authentication CA certificates** endpoint with the default `status` filter. To search for deleted authentication CA certificates, use the query parameter `status=DELETED`.\n", "parameters": [ { "in": "path", "name": "account_id", "required": true, "description": "Account ID (UUID).", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "path", "name": "authentication_certificate_id", "required": true, "description": "Authentication CA certificate ID (UUID).", "schema": { "type": "string", "format": "uuid", "example": "0ee10bb3-76c0-4430-8436-6696b52ffa22" } } ], "responses": { "204": { "description": "Authentication CA certificate deleted. No content." } } } }, "/v1/cert-auth-template": { "post": { "tags": [ "Authentication CA templates" ], "summary": "Create authentication CA template", "operationId": "createAuthenticationCATemplate", "description": "Use this endpoint to create an authentication CA template for an enrollment profile. Authentication CA templates define requirements for certificates that can be used as authentication credentials in the enrollment profile.\n\n## Request format\n\n* **Choose an authentication CA certificate** \nWhen you create an authentication CA template, you choose an authentication CA certificate to validate which of its issued certificates can be used as authentication credentials. You can use an existing authentication CA certificate (`ica_id`), or you can upload a new authentication CA certificate in your request (`ica_body`). **Note:** Authentication CA certificates can only be used in one template per enrollment profile.\n\n* **Define which certificates can be used as authentication credentials** \nTo determine whether there are limits on which certificates issued from the authentication CA certificate can be used as authentication credentials, use the `can_be_used_for_any_certificate` parameter. To define the restrictions, use the `certificate_authentication_type` and `certificate_attributes` parameters.\n\n* **Require a passcode for authentication certificates** \nFor increased security, you may choose to require a passcode for authentication certificates (`force_passcode_for_auth_cert`). When enabled, you create the passcode when you add the authentication certificate to the enrollment profile. API clients using the certificate to authenticate must also provide the passcode in the `x-passcode` request header.\n\n* **Add restrictions and registered values** \nTo define further usage restrictions for authentication certificates, use the `usage_limit`, `start_date`, `end_date`, and `registered_values` parameters.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createAuthenticationCATemplateRequest" } } } }, "responses": { "201": { "description": "Object with authentication CA template details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCATemplateResponse" } } } } } }, "get": { "summary": "List authentication CA templates", "operationId": "listAuthenticationCATemplate", "tags": [ "Authentication CA templates" ], "description": "Use this endpoint to get a list of authentication CA templates, or to search for authentication CA templates that meet the given search criteria.\n", "parameters": [ { "in": "query", "name": "name", "description": "Limits results to authentication CA templates with a name that contains the given string.\n", "schema": { "type": "string", "example": "Authentication CA template name" } }, { "in": "query", "name": "account_id", "description": "Limits results to authentication CA templates assigned to an account ID that is an exact match for the given ID.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "division_id", "description": "Limits results to authentication CA templates for the given division.", "schema": { "type": "string", "format": "uuid", "example": "135fd0f0-62c8-4a89-b8ca-416ae7be2ce3" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to authentication CA templates for the given enrollment profile.", "schema": { "type": "string", "format": "uuid", "example": "e3961d13-a923-447c-b8dc-e5c264b79deb" } }, { "in": "query", "name": "ica_id", "description": "Limits results to authentication CA templates that use the given authentication CA certificate.", "schema": { "type": "string", "format": "uuid", "example": "07d600cd-f386-4218-a2e6-e27cd374c217" } }, { "in": "query", "name": "status", "description": "Limits results to authentication CA templates with the given status. By default, deleted templates do not appear in the results. To search for deleted templates, use `status=DELETED`.\n", "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "use_for_all_certificates", "description": "Filter by value of the `can_be_used_for_any_certificate` field.\n", "schema": { "type": "boolean" } }, { "in": "query", "name": "created_at_from", "description": "Limits results to certificate profiles created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_at_to", "description": "Limits results to certificate profiles created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. Default `sort_by` property is `created_at`.\n", "schema": { "type": "string" } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive. Default `sort_direction` value is `DESC`.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 1000, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with authentication CA template details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of authentication CA templates.", "items": { "$ref": "#/components/schemas/authenticationCATemplateResponse" } } } }, "example": { "limit": 20, "offset": 0, "pagination": true, "next": false, "total": 1, "records": [ { "id": "3d2d0ef3-a815-4be1-8877-0edd1f632c9c", "name": "Example template 1", "certificate_attributes": [], "registered_values": [], "enrollment_profile_id": "IOT_10193f11-6b54-4922-ab49-bddb34460456", "enrollment_profile_name": "EST", "ica_id": "", "ica_common_name": "Example ICA Name", "ica_body": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n", "organization": "Example Organization", "parent_ca": "Example Parent CA", "signature_algorithm": "1.2.840.10045.4.3.3", "key_type": "EC prime256v1", "can_be_used_for_any_certificate": true, "certificate_authentication_type": "not_applicable", "usage_limit": "", "start_date": "", "end_date": "", "expiry_date": "2051-07-20", "status": "ACTIVE", "created_at": "2022-07-21T08:46:40Z", "force_passcode_for_auth_cert": false } ] } } } } } } }, "/v1/cert-auth-template/{authentication_ca_template_id}": { "put": { "summary": "Update authentication CA template", "operationId": "updateAuthenticationCATemplate", "tags": [ "Authentication CA templates" ], "description": "Use this endpoint to update an authentication CA template.\n", "parameters": [ { "in": "path", "name": "authentication_ca_template_id", "description": "Authentication CA template ID (UUID).", "required": true, "schema": { "format": "uuid", "type": "string", "example": "d90e3555-df68-4f7c-a414-9cab52281242" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCATemplateRequest" } } } }, "responses": { "200": { "description": "Object with authentication CA template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCATemplateResponse" } } } } } }, "get": { "summary": "Get authentication CA template", "operationId": "getAuthenticationCATemplate", "tags": [ "Authentication CA templates" ], "description": "Use this endpoint to get details about the given authentication CA template.\n", "parameters": [ { "in": "path", "name": "authentication_ca_template_id", "description": "Authentication CA template ID (UUID).", "required": true, "schema": { "format": "uuid", "type": "string", "example": "d90e3555-df68-4f7c-a414-9cab52281242" } } ], "responses": { "200": { "description": "Object with authentication CA template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCATemplateResponse" } } } } } } }, "/v1/cert-auth-template/{authentication_ca_template_id}/disable": { "put": { "tags": [ "Authentication CA templates" ], "operationId": "disableAuthenticationCATemplate", "summary": "Disable authentication CA template", "description": "Use this endpoint to disable an authentication CA template.\n\nWhen a template is disabled:\n* If `can_be_used_for_any_certificate` is true, authentication credentials associated with the template will be rejected during enrollment.\n* If `can_be_used_for_any_certificate` is false, you cannot create new authentication certificates based on the authentication CA template.\n", "parameters": [ { "in": "path", "name": "authentication_ca_template_id", "description": "Authentication CA template ID (UUID).", "required": true, "schema": { "format": "uuid", "type": "string", "example": "d90e3555-df68-4f7c-a414-9cab52281242" } } ], "responses": { "204": { "description": "Authentication CA template disabled. No content." } } } }, "/v1/cert-auth-template/{authentication_ca_template_id}/delete": { "put": { "tags": [ "Authentication CA templates" ], "operationId": "deleteAuthenticationCATemplate", "summary": "Delete authentication CA template", "description": "Use this endpoint to delete an authentication CA template.\n\nWhen a template is deleted:\n* If `can_be_used_for_any_certificate` is true, authentication credentials associated with the template will be rejected during enrollment.\n* If `can_be_used_for_any_certificate` is false, you cannot create new authentication certificates based on the authentication CA template.\n\nAdditionally, deleted templates do not appear in search results on the **List authentication CA templates** endpoint with the default `status` filter. To search for deleted templates, use the query parameter `status=DELETED`.\n", "parameters": [ { "in": "path", "name": "authentication_ca_template_id", "description": "Authentication CA template ID (UUID).", "required": true, "schema": { "format": "uuid", "type": "string", "example": "d90e3555-df68-4f7c-a414-9cab52281242" } } ], "responses": { "204": { "description": "Authentication CA template deleted. No content." } } } }, "/v1/cert-auth-template/{authentication_ca_template_id}/undelete": { "put": { "tags": [ "Authentication CA templates" ], "operationId": "restoreAuthenticationCATemplate", "summary": "Restore authentication CA template", "description": "Use this endpoint to restore a deleted authentication CA template.\n", "parameters": [ { "in": "path", "name": "authentication_ca_template_id", "description": "Authentication CA template ID (UUID).", "required": true, "schema": { "format": "uuid", "type": "string", "example": "d90e3555-df68-4f7c-a414-9cab52281242" } } ], "responses": { "204": { "description": "Authentication CA template restored. No content." } } } }, "/v1/cert-auth-template/{authentication_ca_template_id}/enable": { "put": { "tags": [ "Authentication CA templates" ], "operationId": "enableAuthenticationCATemplate", "summary": "Enable authentication CA template", "description": "Use this endpoint to enable a disabled authentication CA template.\n", "parameters": [ { "in": "path", "name": "authentication_ca_template_id", "description": "Authentication CA template ID (UUID).", "required": true, "schema": { "format": "uuid", "type": "string", "example": "d90e3555-df68-4f7c-a414-9cab52281242" } } ], "responses": { "204": { "description": "Authentication CA template enabled. No content." } } } }, "/v1/cert-auth-template/assignable-ca/{enrollment_profile_id}": { "get": { "summary": "List assignable authentication CA certificates", "operationId": "listAssignableAuthenticationCACertificates", "tags": [ "Authentication CA templates" ], "description": "Use this endpoint to get a list of authentication CA certificates that can be used in authentication CA templates for the given enrollment profile.\n", "parameters": [ { "in": "path", "name": "enrollment_profile_id", "description": "Enrollment profile ID (UUID).", "required": true, "schema": { "format": "uuid", "type": "string", "example": "ddf6e1ef-8cad-4169-be8b-bb67091c5df7" } }, { "in": "query", "name": "name", "description": "Limits results to authentication CA certificates with a name that contains the given string.", "schema": { "type": "string", "example": "Example CA name" } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20, "example": 1 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with authentication CA certificate details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of objects with authentication CA certificate details.", "items": { "$ref": "#/components/schemas/assignableAuthenticationCACertificateResponse" } } } } } } } } } }, "/v1/authentication-certificate": { "post": { "tags": [ "Authentication certificates" ], "description": "Use this endpoint to add an authentication certificate to an enrollment profile.\n\n**Note:** You only need to add authentication certificates to an enrollment profile when the authentication CA template limits the certificates you can use as authentication credentials. Otherwise, you can authenticate to the **Request certificate** and **Renew certificate** endpoints using any certificates issued from the authentication CA defined in the authentication CA template.\n\n**Request format: `certificate_attributes` vs. `pem`**\n\nWhen creating an authentication CA template, you can choose one of the methods listed below to define which certificates signed by the authentication CA can be used as authentication credentials. The format of your request payload depends on the template’s configuration.\n\n**Method 1**: Define required attributes for authentication certificates\n* The `certificate_attributes` parameter is required.\n* The `pem` request parameter is ignored.\n\n**Method 2**: Upload allowed authentication certificates\n* The `pem` request parameter is required.\n* The `certificate_attributes` parameter is ignored.\n\n**Method 3**: Define required attributes and/or upload the allowed authentication certificates\n* You can either define the required attributes (use `certificate_attributes`) or upload the allowed authentication certificates (use `pem`).\n* Uploading PEM data overrides the `certificate_attributes` object. If the request includes a value for the `pem` parameter, we ignore the `certificate_attributes` object.\n", "summary": "Add authentication certificate", "operationId": "addAuthenticationCertificate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addAuthenticationCertificateRequest" }, "examples": { "upload_pem_certificate": { "summary": "Upload PEM certificate", "description": "Example request to upload an authentication certificate.", "value": { "template_id": "", "pem": "", "name": "Example Authentication Certificate", "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name registered value" }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ] } ] } }, "define_certificate_attributes": { "summary": "Define required certificate attributes", "description": "Example request to define required certificate attributes for authentication credentials.", "value": { "template_id": "", "name": "Example Authentication Certificate", "certificate_attributes": [ { "certificate_attribute": "subject.common_name", "value": "common name" } ], "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name" }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ] } ] } } } } } }, "responses": { "201": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCertificateResponse" }, "examples": { "upload_pem_certificate": { "summary": "Upload PEM certificate", "description": "Example response when uploading authentication certificate.", "value": { "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name", "multiple": false }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ], "multiple": true } ], "id": "", "certificate": { "id": "", "name": "Certificate Name" }, "enrollment_profile": { "id": "", "name": "" }, "number_of_usage": 0, "status": "ACTIVE", "created_at": "2021-05-13T21:05:43.273689Z", "pem": "", "certificate_expires_on": "2022-04-30T17:38:58Z", "certificate_serial_number": "", "certificate_issuer_common_name": "Issuing CA Name", "certificate_status": "ISSUED", "certificate_thumbprint": "", "certificate_organization": "Example Organization", "certificate_organization_units": [], "template_id": "", "use_passcode": false } }, "define_certificate_attributes": { "summary": "Define required certificate attributes", "description": "Example response when defining required certificate attributes for authentication credentials.", "value": { "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name", "multiple": false }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ], "multiple": true } ], "id": "", "enrollment_profile": { "id": "", "name": "" }, "number_of_usage": 0, "status": "ACTIVE", "created_at": "2021-05-13T21:05:43.273689Z", "certificate_issuer_common_name": "Issuing CA Name", "certificate_attributes": [ { "certificate_attribute": "subject.common_name", "value": "common name", "multiple": false } ], "template_id": "", "use_passcode": false } } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "Certificate authentication template with id {template_id} does not exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "get": { "tags": [ "Authentication certificates" ], "description": "Use this endpoint to get a list of authentication certificates.\n", "summary": "List authentication certificates", "operationId": "listAuthenticationCertificates", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to authentication certificates for the account with the given ID.\n", "schema": { "type": "string", "example": "9b7679fa-b1eb-4571-b805-f5a8cc8b520d", "format": "uuid" } }, { "in": "query", "name": "division_id", "description": "Limits results to authentication certificates for the division with the given ID.\n", "schema": { "type": "string", "example": "591c31d2-6b80-455b-95e9-4234aa0c5be7", "format": "uuid" } }, { "in": "query", "name": "name", "description": "Limits results to authentication certificates with a friendly name that contains the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "Example authentication certificate" } }, { "in": "query", "name": "authentication_ca_common_name", "description": "Limits results to authentication certificates associated with authentication CA certificates that have a common name value containing the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "Example authentication CA" } }, { "in": "query", "name": "template_id", "description": "Limits results to authentication certificates created from the authentication CA template with the given ID.\n", "schema": { "type": "string", "example": "5ec09895-b9ed-4a42-b97b-678222c598cc", "format": "uuid" } }, { "in": "query", "name": "authentication_ca_id", "description": "Limits results to authentication certificates associated with the authentication CA certificate with the given ID.\n", "schema": { "type": "string", "example": "c7273059-74a4-4bbc-a9aa-9c2ad7dd1712", "format": "uuid" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to authentication certificates assigned to the enrollment profile with the given ID.\n", "schema": { "type": "string", "example": "IOT_d6b4d0c0-db1a-4d70-83b7-1ccf2f01af7a" } }, { "in": "query", "name": "enrollment_profile_name", "description": "Limits results to authentication certificates assigned to enrollment profiles with a name that contains the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "Example enrollment profile" } }, { "in": "query", "name": "created_from", "description": "Limits results to authentication certificates created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to authentication certificates created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2022-06-30" } }, { "in": "query", "name": "usage_limit_from", "description": "Limits results to authentication certificates with a usage limit higher than the given number. Inclusive.\n", "schema": { "type": "integer", "example": 10 } }, { "in": "query", "name": "usage_limit_to", "description": "Limits results to authentication certificates with a usage limit lower than the given number. Inclusive.\n", "schema": { "type": "integer", "example": 10 } }, { "in": "query", "name": "expires_from", "description": "Limits results to authentication certificates that expire after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2023-12-12" } }, { "in": "query", "name": "expires_to", "description": "Limits results to authentication certificates that expire before the given date Format: `YYYY-MM-DD`\n", "schema": { "format": "date-time", "type": "string", "example": "2025-12-12" } }, { "in": "query", "name": "status", "description": "Limits results to authentication certificates with the given status.\n", "schema": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending (`ASC`) or descending (`DESC`) order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "default": "DESC", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of authentication certificates.", "content": { "application/json": { "schema": { "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of enrollment passcodes .", "items": { "$ref": "#/components/schemas/authenticationCertificateResponse" } } } }, "example": { "limit": 20, "offset": 0, "pagination": true, "next": false, "total": 1, "records": [ { "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name", "multiple": false }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ], "multiple": true } ], "id": "", "certificate": { "id": "", "name": "Certificate Name" }, "enrollment_profile": { "id": "", "name": "" }, "number_of_usage": 0, "status": "ACTIVE", "created_at": "2021-05-13T21:05:43.273689Z", "pem": "", "certificate_expires_on": "2022-04-30T17:38:58Z", "certificate_serial_number": "", "certificate_issuer_common_name": "Issuing CA Name", "certificate_status": "ISSUED", "certificate_thumbprint": "", "certificate_organization": "Example Organization", "certificate_organization_units": [], "certificate_attributes": [], "template_id": "", "use_passcode": false }, { "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name", "multiple": false }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ], "multiple": true } ], "id": "", "certificate": {}, "enrollment_profile": { "id": "", "name": "" }, "number_of_usage": 0, "status": "ACTIVE", "created_at": "2021-05-13T21:05:43.273689Z", "certificate_issuer_common_name": "Issuing CA Name", "certificate_attributes": [ { "certificate_attribute": "subject.common_name", "value": "common name", "multiple": false } ], "template_id": "", "use_passcode": false } ] } } } } } } }, "/v1/authentication-certificate/{authentication_certificate_id}": { "get": { "tags": [ "Authentication certificates" ], "description": "Use this endpoint to get information about an authentication certificate.", "summary": "Get authentication certificate details", "operationId": "getAuthenticationCertificateDetails", "parameters": [ { "$ref": "#/components/parameters/authentication_certificate_id" } ], "responses": { "200": { "description": "Object with authentication certificate details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCertificateResponse" }, "examples": { "upload_pem_certificate": { "summary": "Upload PEM certificate", "description": "Response for certificates that were added via upload.", "value": { "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name", "multiple": false }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ], "multiple": true } ], "id": "", "certificate": { "id": "", "name": "Certificate Name" }, "enrollment_profile": { "id": "", "name": "" }, "number_of_usage": 0, "status": "ACTIVE", "created_at": "2021-05-13T21:05:43.273689Z", "pem": "", "certificate_expires_on": "2022-04-30T17:38:58Z", "certificate_serial_number": "", "certificate_issuer_common_name": "Issuing CA Name", "certificate_status": "ISSUED", "certificate_thumbprint": "", "certificate_organization": "Example Organization", "certificate_organization_units": [], "certificate_attributes": [], "template_id": "", "use_passcode": false } }, "define_certificate_attributes": { "summary": "Define required certificate attributes", "description": "Response for certificates that were added by defining the required attributes.", "value": { "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name", "multiple": false }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ], "multiple": true } ], "id": "", "certificate": {}, "enrollment_profile": { "id": "", "name": "" }, "number_of_usage": 0, "status": "ACTIVE", "created_at": "2021-05-13T21:05:43.273689Z", "certificate_issuer_common_name": "Issuing CA Name", "certificate_attributes": [ { "certificate_attribute": "subject.common_name", "value": "common name", "multiple": false } ], "template_id": "", "use_passcode": false } } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "Certificate authentication template with id {template_id} does not exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "put": { "tags": [ "Authentication certificates" ], "description": "Use this endpoint to update the name, usage restrictions, and registered values for an authentication certificate.\n\n**Warning!** This operation is destructive to the `name`, `start_date`, `end_date`, `usage_limit`, and `registered_values` properties. The values in your request overwrite the existing values for these properties. Omitting a property from your request clears any value already set for that property.\n", "summary": "Update authentication certificate", "operationId": "updateAuthenticationCertificate", "parameters": [ { "$ref": "#/components/parameters/authentication_certificate_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateAuthenticationCertificateRequest" }, "example": { "name": "Updated name", "start_date": "2021-12-05", "end_date": "2022-12-10", "usage_limit": 10, "registered_values": [ { "certificate_field": "subject.common_name", "value": "Updated common name value" } ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authenticationCertificateResponse" }, "examples": { "upload_pem_certificate": { "summary": "Update successful (uploaded certificate)", "description": "Example response when updating credentials you created by uploading an authentication certificate.", "value": { "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name", "multiple": false }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ], "multiple": true } ], "id": "", "name": "Example Name", "certificate": { "id": "", "name": "Certificate Name" }, "enrollment_profile": { "id": "", "name": "" }, "number_of_usage": 0, "status": "ACTIVE", "created_at": "2021-05-13T21:05:43.273689Z", "pem": "", "certificate_expires_on": "2022-04-30T17:38:58Z", "certificate_serial_number": "", "certificate_issuer_common_name": "Issuing CA Name", "certificate_status": "ISSUED", "certificate_thumbprint": "", "certificate_organization": "Example Organization", "certificate_organization_units": [], "template_id": "", "use_passcode": false } }, "define_certificate_attributes": { "summary": "Update successful (defined required certificate attributes)", "description": "Example response when updating credentials you created by defining required certificate attributes for an authentication certificate.", "value": { "start_date": "2021-05-20", "end_date": "2022-05-20", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "common name", "multiple": false }, { "certificate_field": "subject.organization_unit", "matcher": "equals", "value": [ "Unit 1", "Unit 2" ], "multiple": true } ], "id": "", "name": "Example Name", "enrollment_profile": { "id": "", "name": "" }, "number_of_usage": 0, "status": "ACTIVE", "created_at": "2021-05-13T21:05:43.273689Z", "certificate_issuer_common_name": "Issuing CA Name", "certificate_attributes": [ { "certificate_attribute": "subject.common_name", "value": "common name", "multiple": false } ], "template_id": "", "use_passcode": false } } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "Please provide not blank name" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/authentication-certificate/{authentication_certificate_id}/disable": { "put": { "tags": [ "Authentication certificates" ], "summary": "Disable authentication certificate", "operationId": "disableAuthenticationCertificate", "description": "Use this endpoint to disable the authentication certificate with the given ID. Disabled authentication certificates cannot be used as valid credentials during enrollment.\n", "parameters": [ { "$ref": "#/components/parameters/authentication_certificate_id" } ], "responses": { "204": { "description": "Authentication certificate disabled. No content." } } } }, "/v1/authentication-certificate/{authentication_certificate_id}/enable": { "put": { "tags": [ "Authentication certificates" ], "summary": "Enable authentication certificate", "operationId": "enableAuthenticationCertificate", "description": "Use this endpoint to enable the authentication certificate with the given ID.\n", "parameters": [ { "$ref": "#/components/parameters/authentication_certificate_id" } ], "responses": { "204": { "description": "Authentication certificate enabled. No content." } } } }, "/v1/authentication-certificate/{authentication_certificate_id}/delete": { "put": { "tags": [ "Authentication certificates" ], "summary": "Delete authentication certificate", "operationId": "deleteAuthenticationCertificate", "description": "Use this endpoint to delete the authentication certificate with the given ID. Deleted authentication certificates cannot be used as valid credentials during enrollment.\n", "parameters": [ { "$ref": "#/components/parameters/authentication_certificate_id" } ], "responses": { "204": { "description": "Authentication certificate deleted. No content." } } } }, "/v1/authentication-certificate/{authentication_certificate_id}/undelete": { "put": { "tags": [ "Authentication certificates" ], "summary": "Restore authentication certificate", "operationId": "restoreAuthenticationCertificate", "description": "Use this endpoint to restore the deleted authentication certificate with the given ID.\n", "parameters": [ { "$ref": "#/components/parameters/authentication_certificate_id" } ], "responses": { "204": { "description": "Authentication certificate restored. No content." } } } }, "/v1/certificate": { "post": { "tags": [ "Certificates" ], "description": "Use this endpoint to submit a certificate request. To request a certificate via API, your request must include the `enrollment_profile_id` for an enrollment profile that supports the API enrollment method.\n\n## Server-side keypair generation\n\nIf you do not have a certificate signing request (CSR), DigiCert® IoT Trust Manager can generate the private key for you. To learn more, see [Request a certificate with server-side keypair generation](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/request-certificate-with-server-side-keypair-generation.html).\n\n## Authentication\n\nIn addition to header-based API key authentication, the **Request certificate** endpoint supports authentication using an enrollment passcode or a client certificate.\n\n**Client certificate authentication**: With mutual TLS authentication, a client can access the endpoint by presenting a trusted certificate in the request. To use mutual TLS authentication:\n\n* Include a trusted certificate in your request.\n* For the **Request certificate** endpoint, the certificate must be registered to the enrollment profile specified in the request payload.\n* In the base URL for the endpoint path, add the prefix `clientauth`. For example: `https://clientauth.one.digicert.com`\n* Omit the `x-api-key header`.\n\n**Enrollment passcode authentication**: You can authenticate to the **Request certificate** endpoint by presenting an enrollment passcode registered to the enrollment profile specified in the request payload. To authenticate with an enrollment passcode:\n\n* Use the custom HTTP header `x-passcode`. The value of the `x-passcode` header is the passcode associated with the enrollment profile you specify in the body of the request.\n* Omit the `x-api-key` header.\n\n## Certificate request approvals\n\nIf the enrollment profile requires approvals for new certificate requests:\n* The API returns only the request ID with a `status` of `PENDING_APPROVAL`.\n* The following request parameters that describe certificate output formatting are ignored. Instead, clients should describe the output format in the request to download the certificate after the request is approved.\n * `response_with_certificate_only`\n * `split_certificate_response`\n * `include_certificate_chain`\n * `private_key_format`\n * `pkcs12_password`\n * `encryption_certificate`\n \nTo check the status of a pending request, use the [Certificate request status](#/Certificate%20requests/getRequestStatus) endpoint. When the status is APPROVED, use the [Download approved certificate](#/Certificates/downloadApprovedCertificate) endpoint to download the certificate.\n", "operationId": "requestCertificate", "summary": "Request a certificate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestCertificateRequest" }, "examples": { "Client-side keypair generation (includes CSR)": { "value": { "csr": "", "enrollment_profile_id": "IOT_502ac648-c826-4e71-991e-5629a23850c1", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ] } }, "Server-side keypair generation (PEM)": { "value": { "enrollment_profile_id": "IOT_502ac648-c826-4e71-991e-5629a23850c1", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "pem", "private_key_syntax": "pkcs8|sec1_or_pkcs1" } }, "Server-side keypair generation (DER)": { "value": { "enrollment_profile_id": "IOT_502ac648-c826-4e71-991e-5629a23850c1", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "der", "private_key_syntax": "pkcs8|sec1_or_pkcs1" } }, "Server-side keypair generation (PKCS12)": { "value": { "enrollment_profile_id": "IOT_502ac648-c826-4e71-991e-5629a23850c1", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "pkcs_12", "pkcs12_password": "password" } }, "Server-side keypair generation (encrypted)": { "value": { "enrollment_profile_id": "IOT_502ac648-c826-4e71-991e-5629a23850c1", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "cert_encrypted", "private_key_syntax": "pkcs8|sec1_or_pkcs1", "encryption_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n" } } } } } }, "responses": { "200": { "description": "Successfully submitted enrollment request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentResponseObject" }, "examples": { "clientSideDefault": { "$ref": "#/components/examples/clientSideDefault" }, "clientSideWithoutChain": { "$ref": "#/components/examples/clientSideWithoutChain" }, "clientSideSplitCertificateResponse": { "$ref": "#/components/examples/clientSideSplitCertificateResponse" }, "serverSidePEM": { "$ref": "#/components/examples/serverSidePEM" }, "serverSideDER": { "$ref": "#/components/examples/serverSideDER" }, "serverSidePKCS12": { "$ref": "#/components/examples/serverSidePKCS12" }, "serverSideCertEncrypted": { "$ref": "#/components/examples/serverSideCertEncrypted" }, "requestPendingApproval": { "$ref": "#/components/examples/requestPendingApproval" } } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" }, "examples": { "Encrypted ZIP file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `cert_encrypted`, the response is an encrypted ZIP file. The content-type is `application/pkcs7-mime`.\n" } } }, "application/x-pkcs12": { "schema": { "type": "string", "format": "binary" }, "examples": { "PFX file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pkcs_12`, the response is a PFX file. The content-type is `application/x-pkcs12`.\n" } } }, "application/x-pem-file": { "schema": { "type": "string" }, "examples": { "PEM file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pem`, the response is a PEM file. The content-type is `application/x-pem-file`.\n", "value": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Enrollment profile with id {invalid} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "get": { "tags": [ "Certificates" ], "operationId": "listCertificates", "description": "Use this endpoint to get a list of end-entity certificates in DigiCert® IoT Trust Manager.\n\n**Note:** To prevent performance issues, when you call this API endpoint, DigiCert® IoT Trust Manager never calculates the total number of records for pagination. This means:\n\n- The `pagination` response parameter always returns false.\n- The `total` response parameter always returns `0`.\n\nTo check if there is another page of records, use the `next` response parameter. If `next` is true, there is at least one more page of records that you can retrieve by increasing the `offset` in your next request. Otherwise, the current `records` list is the last page.\n", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to certificates with an account ID that is an exact match for the given string.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "division_id", "description": "Limits results to certificates with a division ID that is an exact match for the given string.", "schema": { "type": "string", "format": "uuid", "example": "135fd0f0-62c8-4a89-b8ca-416ae7be2ce3" } }, { "in": "query", "name": "status", "description": "Limits results to certificates with the given status.", "schema": { "type": "string", "example": "ISSUED", "enum": [ "ISSUED", "EXPIRED", "REVOKED" ] } }, { "in": "query", "name": "serial_number", "description": "Limits results to certificates with a serial number that contains the given string.\n", "schema": { "$ref": "#/components/schemas/certificate_serial_number" } }, { "in": "query", "name": "common_name", "description": "Limits results to certificates with a common name that contains the given string.\n", "schema": { "type": "string", "example": "Example common name" } }, { "in": "query", "name": "certificate_value", "description": "Limits results to certificates with a certificate value that contains the given string.", "schema": { "example": "Certificate value", "type": "string" } }, { "in": "query", "name": "device_identifier", "description": "Limits results to certificates with a device name (`device_identifier`) that contains the given string.", "schema": { "example": "Device name", "type": "string" } }, { "in": "query", "name": "device_id", "description": "Limits results to certificates with a device ID that is an exact match for the given string.", "schema": { "example": "b85f78a0-b083-46f3-bc71-92e892a81a45", "type": "string" } }, { "in": "query", "name": "enrollment_method", "description": "Limits results to certificates issued using the given enrollment method.\n", "schema": { "type": "string", "example": "API", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH" ] } }, { "in": "query", "name": "enrollment_method", "description": "Limits results to certificates issued using the given enrollment method.\n", "schema": { "type": "string", "example": "API", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH" ] } }, { "in": "query", "name": "created_from", "description": "Limits results to certificates created after the given date. UTC timezone. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to certificates created before the given date. UTC timezone. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "valid_to_start", "description": "Limits results to certificates with a `valid_to` value on or after the given date or date-time. Use with `valid_to_end` to search for certificates with a `valid_to` date in a specific range. UTC timezone. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "format": "date-time", "example": "2021-04-22", "type": "string" } }, { "in": "query", "name": "valid_to_end", "description": "Limits results to certificates with a `valid_to` value on or before the given date or date-time. Use with `valid_to_start` to search for certificates with a `valid_to` date in a specific range. UTC timezone. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "format": "date-time", "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "issuer_common_name", "description": "Limits results to certificates issued from a CA with a common name that contains the given string.\n", "schema": { "type": "string", "example": "Issuer common name" } }, { "in": "query", "name": "issuer_serial_number", "description": "Limits results to certificates issued from the CA with a serial number that is an exact match for the given string.\n", "schema": { "type": "string", "example": "1234D1B7345647B5B6F95F572E8C917D5A123456" } }, { "in": "query", "name": "key_type", "description": "Limits results to certificates with key type that contains the given string.\n", "schema": { "type": "string", "example": "RSA" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to certificates issued using an enrollment profile with an ID that is an exact match for the given string.\n", "schema": { "type": "string", "example": "IOT_07ccbdc1-35d9-6ba2-7d3b-197b2c456088" } }, { "in": "query", "name": "revoked_from", "description": "Limits results to certificates revoked after a specific date. UTC timezone. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "revoked_to", "description": "Limits results to certificates revoked before a specific date. UTC timezone. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "ocsp_group", "description": "Filter results using OCSP group ID. Must be an exact match. Modified using `included_in_ocsp_group`.\n", "schema": { "type": "string", "example": "" } }, { "in": "query", "name": "included_in_ocsp_group", "description": "If true, limits results to certificates included in the given `ocsp_group`. If false, limits results to certificates excluded from the given `ocsp_group`. If omitted, no `ocsp_group` filter is applied.\n", "schema": { "type": "boolean", "example": true } }, { "in": "query", "name": "device_id", "description": "Limits results to certificates with a device ID that is an exact match for the given string.\n", "schema": { "type": "string", "format": "uuid", "example": "a22b9829-361f-4a9d-a402-714d5521fae4" } }, { "in": "query", "name": "certificate_type", "description": "Limits results to certificates of the given type.\n", "schema": { "type": "string", "example": "x509", "enum": [ "x509", "global-platform", "attribute-certificate" ] } }, { "in": "query", "name": "created_in_last_n_days", "description": "Limits results to certificates created in the last *n* days, where *n* is a numerical value you provide in your request.\n", "schema": { "type": "number", "example": 20 } }, { "in": "query", "name": "created_in_current_month", "description": "If true, limits results to certificates created in the current month.\n", "schema": { "type": "boolean", "example": true, "default": false } }, { "in": "query", "name": "created_in_previous_month", "description": "If true, limits results to certificates created in the previous month.\n", "schema": { "type": "boolean", "example": true, "default": false } }, { "in": "query", "name": "expiring_in_next_n_days", "description": "Limits results to certificates expiring in the next *n* days, where *n* is a numerical value you provide in your request.\n", "schema": { "type": "number", "example": 20 } }, { "in": "query", "name": "expiring_in_remaining_of_current_month", "description": "If true, limits results to certificates expiring before the end of the current month.\n", "schema": { "type": "number", "example": 20 } }, { "in": "query", "name": "expiring_in_next_month", "description": "If true, limits results to certificates expiring before the end of the next month.\n", "schema": { "type": "number", "example": 20 } }, { "in": "query", "name": "key_usage", "description": "Limits results to certificates with the given key usage extension.\n", "schema": { "type": "string", "example": "digital_signature" } }, { "in": "query", "name": "extended_key_usage", "description": "Limits results to certificates with the given extended key usage (EKU) extension.\n", "schema": { "type": "string", "example": "client_authentication" } }, { "in": "query", "name": "certificate_policies", "description": "Limits results to certificates with the given certificate policies.\n", "schema": { "type": "string", "example": "" } }, { "in": "query", "name": "authentication_id", "description": "Limits results to certificates requested with an authentication ID that contains the given string.\n", "schema": { "type": "string", "example": "20a96dd7-3a14-4e5d-8949-c869b24997cd" } }, { "in": "query", "name": "authentication_type", "description": "Limits results to certificates requested with the given authentication type.\n", "schema": { "type": "string", "example": "user", "enum": [ "user", "passcode", "certificate", "authentication_ca", "authentication_certificate" ] } }, { "in": "query", "name": "authentication_name", "description": "Limits results to certificates requested with an authentication name that contains the given string.\n", "schema": { "type": "string", "example": "local.admin" } }, { "in": "query", "name": "ca_connector_type", "description": "Limits results to certificates with the given CA connector type.\n", "schema": { "type": "string", "enum": [ "digicert_one", "digicert_cis" ] } }, { "in": "query", "name": "renewed", "description": "If present, limits results to certificates that have been renewed (`?renewed=true`) or not renewed (`?renewed=false`).\n", "schema": { "type": "boolean" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. If not provided, results are sorted in descending order by date created (`created_at`).\n", "schema": { "type": "string", "enum": [ "created_at", "certificate_value", "valid_from", "valid_to" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20, "example": 1 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "summary": "List certificates", "responses": { "200": { "description": "List of certificates that meet the given search criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "type": "boolean", "description": "If true, the API calculates the total number of records and returns this number in the `total` response parameter. If false, the API does not calculate the total number of records, and the `total` response parameter returns `0`.\n\n**Note:** For the List certificates API endpoint, the API never calculates the total number of records, and `pagination` always returns false. To check if there is another page of records, use the `next` response parameter. If `next` is true, there is at least one more page of records that you can retrieve by increasing the `offset` in your next request. Otherwise, the current `records` list is the last page.\n", "example": false }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of certificates.", "items": { "$ref": "#/components/schemas/certificateDetails" } } } } } } } } } }, "/v1/certificate/{certificate_id}/example-request": { "get": { "tags": [ "Certificates" ], "summary": "Get example certificate request by certificate ID", "operationId": "getExampleCertificateRequestCertificateID", "description": "Use this endpoint to get an example of the JSON request body that was used to request the given certificate.\n\nThe enrollment profile that issued the certificate must use an enrollment method of API or PORTAL.\n", "parameters": [ { "$ref": "#/components/parameters/certificate_id" } ], "responses": { "200": { "description": "Example certificate request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestCertificateRequest" }, "example": { "enrollment_profile_id": "IOT_374599fd-beb1-45b3-91e4-26016463ce2f", "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "URIplusRID" }, { "id": "subject.organization_name", "value": "DC" }, { "id": "subject.country", "value": "US" }, { "id": "san.dns_name", "value": [ "example.com", "example.org" ] } ], "custom_attributes": [], "device_attributes": [ { "id": "DEVICE_IDENTIFIER", "value": "DevId" }, { "id": "e2854683-660b-4794-a1ee-6a95bf3b13a9", "value": "m1" }, { "id": "b1532c2c-a197-483a-a7dc-aff7aa23f7b4", "value": "o2" } ], "response_with_certificate_only": false, "split_certificate_response": true, "include_certificate_chain": true, "server_side_key_gen": false } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "errors": [ { "code": "entity_not_found", "message": "Certificate with ID {invalid} does not exist" } ] } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "{message}" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } } }, "/v1/certificate/{certificate_id}/renew": { "put": { "tags": [ "Certificates" ], "operationId": "renewCertificate", "summary": "Renew a certificate by certificate ID", "description": "Use this endpoint to renew the certificate with the given ID within the renewal window. If `csr` or other attributes is not provided then values from original certificate request will be used for certificate enrollment. Allow to pass empty request body.\n\n## Server-side keypair generation\n\nIf you do not have a certificate signing request (CSR), DigiCert® IoT Trust Manager can generate the private key for you. To learn more, see [Request a certificate with server-side keypair generation](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/request-certificate-with-server-side-keypair-generation.html).\n\n## Authentication\n\nIn addition to header-based API key authentication, the **Renew certificate** endpoint supports authentication using an enrollment passcode or a client certificate.\n\n**Client certificate authentication**: With mutual TLS authentication, a client can access the endpoint by presenting a trusted certificate in the request. To use mutual TLS authentication:\n\n* Include a trusted certificate in your request.\n* For the **Renew certificate** endpoint, the certificate must be registered to the enrollment profile specified in the request payload.\n* In the base URL for the endpoint path, add the prefix `clientauth`. For example: `https://clientauth.one.digicert.com`\n* Omit the `x-api-key header`.\n\n**Enrollment passcode authentication**: You can authenticate to the **Renew certificate** endpoint by presenting an enrollment passcode registered to the enrollment profile specified in the request payload. To authenticate with an enrollment passcode:\n\n* Use the custom HTTP header `x-passcode`. The value of the `x-passcode` header is the passcode associated with the enrollment profile you specify in the body of the request.\n* Omit the `x-api-key` header.\n\n## Renewal approvals\n\nIf the enrollment profile requires approvals for certificate renewals:\n* The API returns only the request ID with a `status` of `PENDING_APPROVAL`.\n* The following request parameters that describe certificate output formatting are ignored. Instead, clients should describe the output format in the request to download the certificate after the request is approved.\n * `response_with_certificate_only`\n * `split_certificate_response`\n * `include_certificate_chain`\n * `private_key_format`\n * `pkcs12_password`\n * `encryption_certificate`\n\nTo check the status of a pending request, use the [Certificate request status](#/Certificate%20requests/getRequestStatus) endpoint. When the status is APPROVED, use the [Download approved certificate](#/Certificates/downloadApprovedCertificate) endpoint to download the certificate.\n", "parameters": [ { "$ref": "#/components/parameters/certificate_id" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/renewCertificateRequest" }, { "properties": { "include_certificate_chain": { "type": "boolean", "description": "If true (default), response includes data for each certificate in the certificate chain (for example, end-entity certificate, intermediate CA certificate, and root certificate). If false, response includes data for the end-entity certificate only.\n", "example": true, "default": true }, "split_certificate_response": { "type": "boolean", "description": "If true, each certificate in the certificate chain is returned in a separate field. The `pem` field contains the end-entity certificate, and the `chain` field contains a list of objects with intermediate CA and root certificate data. If false (default), the `pem` field contains the entire certificate chain, and no `chain` array is returned.", "example": false, "default": false } } } ] }, "examples": { "Client-side keypair generation (includes CSR)": { "value": { "csr": "", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ] } }, "Server-side keypair generation (PEM)": { "value": { "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "pem" } }, "Server-side keypair generation (PKCS12)": { "value": { "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "pkcs_12", "pkcs12_password": "password" } }, "Server-side keypair generation (encrypted)": { "value": { "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "cert_encrypted", "encryption_certificate": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" } } } } } }, "responses": { "200": { "description": "Renewed certificate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentResponseObject" }, "examples": { "clientSideDefault": { "$ref": "#/components/examples/clientSideDefault" }, "clientSideWithoutChain": { "$ref": "#/components/examples/clientSideWithoutChain" }, "clientSideSplitCertificateResponse": { "$ref": "#/components/examples/clientSideSplitCertificateResponse" }, "serverSidePEM": { "$ref": "#/components/examples/serverSidePEM" }, "serverSidePKCS12": { "$ref": "#/components/examples/serverSidePKCS12" }, "serverSideCertEncrypted": { "$ref": "#/components/examples/serverSideCertEncrypted" }, "requestPendingApproval": { "$ref": "#/components/examples/requestPendingApproval" } } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" }, "examples": { "Encrypted ZIP file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `cert_encrypted`, the response is an encrypted ZIP file. The content-type is `application/pkcs7-mime`.\n" } } }, "application/x-pkcs12": { "schema": { "type": "string", "format": "binary" }, "examples": { "PFX file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pkcs_12`, the response is a PFX file. The content-type is `application/x-pkcs12`.\n" } } }, "application/x-pem-file": { "schema": { "type": "string" }, "examples": { "PEM file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pem`, the response is a PEM file. The content-type is `application/x-pem-file`.\n", "value": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "errors": [ { "code": "entity_not_found", "message": "Certificate with ID {invalid} does not exist" } ] } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "{message}" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } } }, "/v1/certificate/serial-number/{certificate_serial_number}/renew": { "put": { "tags": [ "Certificates" ], "operationId": "renewBySerial", "summary": "Renew a certificate by serial number", "description": "Use this endpoint to renew the certificate with the given serial number within the renewal window. If `csr` or other attributes is not provided then values from original certificate request will be used for certificate enrollment. Allow to pass empty request body.\n\n## Server-side keypair generation\n\nIf you do not have a certificate signing request (CSR), DigiCert® IoT Trust Manager can generate the private key for you. To learn more, see [Request a certificate with server-side keypair generation](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/request-certificate-with-server-side-keypair-generation.html).\n\n## Authentication\n\nIn addition to header-based API key authentication, the **Renew certificate** endpoint supports authentication using an enrollment passcode or a client certificate.\n\n**Client certificate authentication**: With mutual TLS authentication, a client can access the endpoint by presenting a trusted certificate in the request. To use mutual TLS authentication:\n\n* Include a trusted certificate in your request.\n* For the **Renew certificate** endpoint, the certificate must be registered to the enrollment profile specified in the request payload.\n* In the base URL for the endpoint path, add the prefix `clientauth`. For example: `https://clientauth.one.digicert.com`\n* Omit the `x-api-key header`.\n\n**Enrollment passcode authentication**: You can authenticate to the **Renew certificate** endpoint by presenting an enrollment passcode registered to the enrollment profile specified in the request payload. To authenticate with an enrollment passcode:\n\n* Use the custom HTTP header `x-passcode`. The value of the `x-passcode` header is the passcode associated with the enrollment profile you specify in the body of the request.\n* Omit the `x-api-key` header.\n\n## Certificate request approvals\n\nIf the enrollment profile requires approvals for new certificate requests:\n* The API returns only the request ID with a `status` of `PENDING_APPROVAL`.\n* The following request parameters that describe certificate output formatting are ignored. Instead, clients should describe the output format in the request to download the certificate after the request is approved.\n * `response_with_certificate_only`\n * `split_certificate_response`\n * `include_certificate_chain`\n * `private_key_format`\n * `pkcs12_password`\n * `encryption_certificate`\n\nTo check the status of a pending request, use the [Certificate request status](#/Certificate%20requests/getRequestStatus) endpoint. When the status is APPROVED, use the [Download approved certificate](#/Certificates/downloadApprovedCertificate) endpoint to download the certificate.\n", "parameters": [ { "$ref": "#/components/parameters/certificate_serial_number" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/renewCertificateRequest" }, { "properties": { "include_certificate_chain": { "type": "boolean", "description": "If true (default), response includes data for each certificate in the certificate chain (for example, end-entity certificate, intermediate CA certificate, and root certificate). If false, response includes data for the end-entity certificate only.\n", "example": true, "default": true }, "split_certificate_response": { "type": "boolean", "description": "If true, each certificate in the certificate chain is returned in a separate field. The `pem` field contains the end-entity certificate, and the `chain` field contains a list of objects with intermediate CA and root certificate data. If false (default), the `pem` field contains the entire certificate chain, and no `chain` array is returned.", "example": false, "default": false } } } ] }, "examples": { "Client-side keypair generation (includes CSR)": { "value": { "csr": "", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ] } }, "Server-side keypair generation (PEM)": { "value": { "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "pem" } }, "Server-side keypair generation (PKCS12)": { "value": { "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "pkcs_12", "pkcs12_password": "password" } }, "Server-side keypair generation (encrypted)": { "value": { "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "cert_encrypted", "encryption_certificate": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" } } } } } }, "responses": { "200": { "description": "Certificate renewal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentResponseObject" }, "examples": { "clientSideDefault": { "$ref": "#/components/examples/clientSideDefault" }, "clientSideWithoutChain": { "$ref": "#/components/examples/clientSideWithoutChain" }, "clientSideSplitCertificateResponse": { "$ref": "#/components/examples/clientSideSplitCertificateResponse" }, "serverSidePEM": { "$ref": "#/components/examples/serverSidePEM" }, "serverSidePKCS12": { "$ref": "#/components/examples/serverSidePKCS12" }, "serverSideCertEncrypted": { "$ref": "#/components/examples/serverSideCertEncrypted" }, "requestPendingApproval": { "$ref": "#/components/examples/requestPendingApproval" } } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" }, "examples": { "Encrypted ZIP file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `cert_encrypted`, the response is an encrypted ZIP file. The content-type is `application/pkcs7-mime`.\n" } } }, "application/x-pkcs12": { "schema": { "type": "string", "format": "binary" }, "examples": { "PFX file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pkcs_12`, the response is a PFX file. The content-type is `application/x-pkcs12`.\n" } } }, "application/x-pem-file": { "schema": { "type": "string" }, "examples": { "PEM file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pem`, the response is a PEM file. The content-type is `application/x-pem-file`.\n", "value": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "errors": [ { "code": "entity_not_found", "message": "Certificate with ID {invalid} does not exist" } ] } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "{message}" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } } }, "/v1/certificate/renew": { "put": { "tags": [ "Certificates" ], "operationId": "renewCertificateByBody", "summary": "Renew a certificate by certificate body", "description": "Use this endpoint to renew the certificate by certificate body within the renewal window. If `csr` or other attributes is not provided then values from original certificate request will be used for certificate enrollment.\n\n## Server-side keypair generation\n\nIf you do not have a certificate signing request (CSR), DigiCert® IoT Trust Manager can generate the private key for you. To learn more, see [Request a certificate with server-side keypair generation](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/request-certificate-with-server-side-keypair-generation.html).\n\n## Authentication\n\nIn addition to header-based API key authentication, the **Renew certificate** endpoint supports authentication using an enrollment passcode or a client certificate.\n\n**Client certificate authentication**: With mutual TLS authentication, a client can access the endpoint by presenting a trusted certificate in the request. To use mutual TLS authentication:\n\n* Include a trusted certificate in your request.\n* For the **Renew certificate** endpoint, the certificate must be registered to the enrollment profile specified in the request payload.\n* In the base URL for the endpoint path, add the prefix `clientauth`. For example: `https://clientauth.one.digicert.com`\n* Omit the `x-api-key header`.\n\n**Enrollment passcode authentication**: You can authenticate to the **Renew certificate** endpoint by presenting an enrollment passcode registered to the enrollment profile specified in the request payload. To authenticate with an enrollment passcode:\n\n* Use the custom HTTP header `x-passcode`. The value of the `x-passcode` header is the passcode associated with the enrollment profile you specify in the body of the request.\n* Omit the `x-api-key` header.\n\n## Renewal approvals\n\nIf the enrollment profile requires approvals for certificate renewals:\n* The API returns only the request ID with a `status` of `PENDING_APPROVAL`.\n* The following request parameters that describe certificate output formatting are ignored. Instead, clients should describe the output format in the request to download the certificate after the request is approved.\n * `response_with_certificate_only`\n * `split_certificate_response`\n * `include_certificate_chain`\n * `private_key_format`\n * `pkcs12_password`\n * `encryption_certificate`\n\nTo check the status of a pending request, use the [Certificate request status](#/Certificate%20requests/getRequestStatus) endpoint. When the status is APPROVED, use the [Download approved certificate](#/Certificates/downloadApprovedCertificate) endpoint to download the certificate.\n", "parameters": [ { "$ref": "#/components/parameters/certificate_id" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/renewCertificateRequestByBody" }, { "properties": { "include_certificate_chain": { "type": "boolean", "description": "If true (default), response includes data for each certificate in the certificate chain (for example, end-entity certificate, intermediate CA certificate, and root certificate). If false, response includes data for the end-entity certificate only.\n", "example": true, "default": true }, "split_certificate_response": { "type": "boolean", "description": "If true, each certificate in the certificate chain is returned in a separate field. The `pem` field contains the end-entity certificate, and the `chain` field contains a list of objects with intermediate CA and root certificate data. If false (default), the `pem` field contains the entire certificate chain, and no `chain` array is returned.", "example": false, "default": false } } } ] }, "examples": { "Client-side keypair generation (includes CSR)": { "value": { "certificate_to_renew": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----", "csr": "", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ] } }, "Server-side keypair generation (PEM)": { "value": { "certificate_to_renew": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "pem" } }, "Server-side keypair generation (PKCS12)": { "value": { "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "pkcs_12", "pkcs12_password": "password" } }, "Server-side keypair generation (encrypted)": { "value": { "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "custom common name" } ], "device_attributes": [ { "id": "party-no", "value": "PN8363454893" } ], "server_side_key_gen": true, "key_type": "rsa_2048", "private_key_format": "cert_encrypted", "encryption_certificate": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" } } } } } }, "responses": { "200": { "description": "Renewed certificate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentResponseObject" }, "examples": { "clientSideDefault": { "$ref": "#/components/examples/clientSideDefault" }, "clientSideWithoutChain": { "$ref": "#/components/examples/clientSideWithoutChain" }, "clientSideSplitCertificateResponse": { "$ref": "#/components/examples/clientSideSplitCertificateResponse" }, "serverSidePEM": { "$ref": "#/components/examples/serverSidePEM" }, "serverSidePKCS12": { "$ref": "#/components/examples/serverSidePKCS12" }, "serverSideCertEncrypted": { "$ref": "#/components/examples/serverSideCertEncrypted" }, "requestPendingApproval": { "$ref": "#/components/examples/requestPendingApproval" } } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" }, "examples": { "Encrypted ZIP file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `cert_encrypted`, the response is an encrypted ZIP file. The content-type is `application/pkcs7-mime`.\n" } } }, "application/x-pkcs12": { "schema": { "type": "string", "format": "binary" }, "examples": { "PFX file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pkcs_12`, the response is a PFX file. The content-type is `application/x-pkcs12`.\n" } } }, "application/x-pem-file": { "schema": { "type": "string" }, "examples": { "PEM file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pem`, the response is a PEM file. The content-type is `application/x-pem-file`.\n", "value": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "errors": [ { "code": "entity_not_found", "message": "Certificate with ID {invalid} does not exist" } ] } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "{message}" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } } }, "/v1/certificate/{certificate_id}/revoke": { "put": { "tags": [ "Certificates" ], "operationId": "revokeCertificate", "summary": "Revoke a certificate by certificate ID", "description": "Use this endpoint to revoke a certificate with the given certificate ID.", "parameters": [ { "$ref": "#/components/parameters/certificate_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/revokeCertificateRequest" } } } }, "responses": { "204": { "description": "Revocation successful (no content)." }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Certificate with ID {invalid} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "Revocation date should not be in the future" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/certificate/{certificate_id}/note": { "put": { "tags": [ "Certificates" ], "operationId": "updateNote", "summary": "Update certificate note", "description": "Use this endpoint to update the note for a certificate.", "parameters": [ { "$ref": "#/components/parameters/certificate_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "$ref": "#/components/schemas/note" } } } } } }, "responses": { "200": { "description": "Certificate details with new `note` value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateDetails" } } } } } } }, "/v1/certificate/serial-number/{certificate_serial_number}/revoke": { "put": { "tags": [ "Certificates" ], "operationId": "revokeCertificateBySerialNumber", "summary": "Revoke a certificate by serial number", "description": "Use this endpoint to revoke a certificate with the given serial number.", "parameters": [ { "$ref": "#/components/parameters/certificate_serial_number" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/revokeCertificateRequest" } } } }, "responses": { "204": { "description": "Revocation successful (no content)." }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "Revocation date should not be in the future" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } } }, "/v1/certificate/{certificate_id}/download/{format}": { "get": { "tags": [ "Certificates" ], "operationId": "downloadCertificate", "summary": "Download a certificate by certificate ID", "description": "Use this endpoint to download a certificate with the given certificate ID.\n", "parameters": [ { "$ref": "#/components/parameters/certificate_id" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "The certificate data in the chosen format.", "content": { "application/x-pem-file": { "schema": { "type": "string", "description": "Single .pem file with certificate data.", "example": "-----BEGIN CERTIFICATE-----\nNIIEwzCCA6ugAwIBAgIUQlTmb7G0ioO8HAfGaijM7Rmsmm8wDQYJKoZIhvcNAQEL\nBQAwgaYxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJVVDEPMA0GA1UEBxMGRHJhcGVy\nMSMwJQYDVQQJExo5MDcgRWFzdCBTYXBwaGlyZSBIaWxsIFdheTEjMCEGA1UEERMa\nOTA3IEVhc3QgU2FwcGhpcmUgSGlsbCBXYXkxETAPBgNVBAoTCGpUZXN0T3JnMRww\nGgYDVQQDExNqVGVzdE9yZyBJc3N1aW5nIENBMB4XDTIwMTIwMTIzNDQzOVoXDTIx\nMDQzMDIxMjQxMlowPjELMAkGA1UEBhMCVVMxGjAYBgNVBAoTEUJpZyBib2IncyBi\nZWVwZXJzMRMwEQYDVQQDEwpyZXZvYWsuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOC\nAQ8AMIIBCgKCAQEA1MInibYzag7sD8n2st0C8PiQEsukzDFV4BmXgcoNKyFUYUJR\n24E7/UiDr6tIxP2bgMh9n+7nSUsWBlJRpcCtgiiZ+WDVuSgZOwv+qRNrDZh8nVix\noGGueYpp8wFPCrpbfFksQkQ1dtQpjyHIAVDuCzN23PBrLwe3lGlkFcemp0VrJLjU\nisbJkjwKB6m/b1j7NJL15SRadPpH3jHH6fqNvva8U6+6OuhbAazJp8uYPHhcX8Ak\nkWpH7QwGjVQOAIakg8jFYYYQgQOD6iCIcuYbvwx6UcErTKXU5gONM0OscBSgRmHJ\nbOVyya8b7bmG0Rnbk7pVAp1tpkZKdLFGoqYRdwIDAQABo4IBTjCCAUowDAYDVR0T\nAQH/BAIwADAdBgNVHQ4EFgQUf1jmjNqh/1gUsmEqghJ/SptvDTYwHwYDVR0jBBgw\nFoAUPUTdP9eofWk0Z1bicIZWmofIJRMwDgYDVR0PAQH/BAQDAgWgMBYGA1UdJQEB\n/wQMMAoGCCsGAQUFBwMBMIGHBggrBgEFBQcBAQR7MHkwLgYIKwYBBQUHMAGGImh0\ndHA6Ly9vY3NwLnN0YWdlLm9uZS5kaWdpY2VydC5jb20wRwYIKwYBBQUHMAKGO2h0\ndHA6Ly9jYWNlcnRzLnN0YWdlLm9uZS5kaWdpY2VydC5jb20valRlc3RPcmdJc3N1\naW5nQ0EuY3J0MEgGA1UdHwRBMD8wPaA7oDmGN2h0dHA3Ly9jcmwuc3RhZ2Uub25l\nLmRpZ2ljZXJ0LmNvbS9qVGVzdE9yZ0lzc3VpbmdDQS5jbmwwDQYJKoZIhvcNAQEL\nBQADggEBAIvd+M2SUsuDYzxLnKm+LqlL3Sccnr3n2M2tF6Vj61c6CVDDgLhLmqu/\nAxVPLSaZQfoUsjVGAbxduTO9NBDtTZ90PQQpe4EgKJd8WdfhlFUwDx5wYQp6ibFm\nHT9+ekSCGsVdbdBKhR6OUyc/n+KTQU3Gmo3bemKuRIKkZL1evCKQFZFgdZq0gqH6\nN7/3jccs1pL8vsIj8+W1HV9i8nOoFCKamadxqkf/wPmaGP+suuR/yeq32LJpliPE\nNtIn4XXeulxhoc2fpOQJHKYfI17VUs7IkZjIHlmg8KxU7VQjUYEriusCsE9m3QPd\nUHvRXcPfNOSCfVAGdK0n5OSV28OdBH4=\n-----END CERTIFICATE-----\n" } }, "application/zip": { "schema": { "type": "string", "format": "binary", "description": "Zip file with end-entity, intermediate, and root certificates in the chosen format." } }, "application/x-pkcs7-certificates": { "schema": { "type": "string", "format": "binary", "description": "End-entity certificate with .p7b or .cer extension, depending on the chosen format." } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Certificate with ID {invalid} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `VIEW_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/certificate/serial-number/{certificate_serial_number}/download/{format}": { "get": { "tags": [ "Certificates" ], "operationId": "downloadCertificateBySerialNumber", "summary": "Download a certificate by serial number", "description": "Use this endpoint to download a certificate with the given serial number.", "parameters": [ { "$ref": "#/components/parameters/certificate_serial_number" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "The certificate data in the chosen format.", "content": { "application/x-pem-file": { "schema": { "type": "string", "description": "Single .pem file with certificate data.", "example": "-----BEGIN CERTIFICATE-----\nNIIEwzCCA6ugAwIBAgIUQlTmb7G0ioO8HAfGaijM7Rmsmm8wDQYJKoZIhvcNAQEL\nBQAwgaYxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJVVDEPMA0GA1UEBxMGRHJhcGVy\nMSMwJQYDVQQJExo5MDcgRWFzdCBTYXBwaGlyZSBIaWxsIFdheTEjMCEGA1UEERMa\nOTA3IEVhc3QgU2FwcGhpcmUgSGlsbCBXYXkxETAPBgNVBAoTCGpUZXN0T3JnMRww\nGgYDVQQDExNqVGVzdE9yZyBJc3N1aW5nIENBMB4XDTIwMTIwMTIzNDQzOVoXDTIx\nMDQzMDIxMjQxMlowPjELMAkGA1UEBhMCVVMxGjAYBgNVBAoTEUJpZyBib2IncyBi\nZWVwZXJzMRMwEQYDVQQDEwpyZXZvYWsuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOC\nAQ8AMIIBCgKCAQEA1MInibYzag7sD8n2st0C8PiQEsukzDFV4BmXgcoNKyFUYUJR\n24E7/UiDr6tIxP2bgMh9n+7nSUsWBlJRpcCtgiiZ+WDVuSgZOwv+qRNrDZh8nVix\noGGueYpp8wFPCrpbfFksQkQ1dtQpjyHIAVDuCzN23PBrLwe3lGlkFcemp0VrJLjU\nisbJkjwKB6m/b1j7NJL15SRadPpH3jHH6fqNvva8U6+6OuhbAazJp8uYPHhcX8Ak\nkWpH7QwGjVQOAIakg8jFYYYQgQOD6iCIcuYbvwx6UcErTKXU5gONM0OscBSgRmHJ\nbOVyya8b7bmG0Rnbk7pVAp1tpkZKdLFGoqYRdwIDAQABo4IBTjCCAUowDAYDVR0T\nAQH/BAIwADAdBgNVHQ4EFgQUf1jmjNqh/1gUsmEqghJ/SptvDTYwHwYDVR0jBBgw\nFoAUPUTdP9eofWk0Z1bicIZWmofIJRMwDgYDVR0PAQH/BAQDAgWgMBYGA1UdJQEB\n/wQMMAoGCCsGAQUFBwMBMIGHBggrBgEFBQcBAQR7MHkwLgYIKwYBBQUHMAGGImh0\ndHA6Ly9vY3NwLnN0YWdlLm9uZS5kaWdpY2VydC5jb20wRwYIKwYBBQUHMAKGO2h0\ndHA6Ly9jYWNlcnRzLnN0YWdlLm9uZS5kaWdpY2VydC5jb20valRlc3RPcmdJc3N1\naW5nQ0EuY3J0MEgGA1UdHwRBMD8wPaA7oDmGN2h0dHA3Ly9jcmwuc3RhZ2Uub25l\nLmRpZ2ljZXJ0LmNvbS9qVGVzdE9yZ0lzc3VpbmdDQS5jbmwwDQYJKoZIhvcNAQEL\nBQADggEBAIvd+M2SUsuDYzxLnKm+LqlL3Sccnr3n2M2tF6Vj61c6CVDDgLhLmqu/\nAxVPLSaZQfoUsjVGAbxduTO9NBDtTZ90PQQpe4EgKJd8WdfhlFUwDx5wYQp6ibFm\nHT9+ekSCGsVdbdBKhR6OUyc/n+KTQU3Gmo3bemKuRIKkZL1evCKQFZFgdZq0gqH6\nN7/3jccs1pL8vsIj8+W1HV9i8nOoFCKamadxqkf/wPmaGP+suuR/yeq32LJpliPE\nNtIn4XXeulxhoc2fpOQJHKYfI17VUs7IkZjIHlmg8KxU7VQjUYEriusCsE9m3QPd\nUHvRXcPfNOSCfVAGdK0n5OSV28OdBH4=\n-----END CERTIFICATE-----\n" } }, "application/zip": { "schema": { "type": "string", "format": "binary", "description": "Zip file with end-entity, intermediate, and root certificates in the chosen format." } }, "application/x-pkcs7-certificates": { "schema": { "type": "string", "format": "binary", "description": "End-entity certificate with .p7b or .cer extension, depending on the chosen format." } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "{message}" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `VIEW_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } } }, "/v1/certificate-import/{enrollment_profile_id}": { "post": { "tags": [ "Certificates" ], "operationId": "importCertificate", "summary": "Import certificates", "description": "Use this endpoint to import one or more certificates for an enrollment profile that uses the **Certificate Import** enrollment method.\n\nBefore you import certificates, you must set up source fields mapping in the enrollment profile. Then, when you import certificates, the files with your certificate data must use the same file type extension (.pem or .xml) as the file that you used to set up source fields mapping.\n\nThe request uses a content type of multipart/form-data. The body of the request is a compressed .zip file that contains one of the following:\n* One or more .pem certificate files for each certificate to upload.\n* An .xml file with the PEM-encoded certificate data for each certificate to upload. PEM-encoded data should not include line breaks or certificate headers and footers.\n\nThe XML data structure for importing certificates is as follows:\n\n```\n\n\n\n \n {{pem_data}}\n \n \n {{pem_data}}\n \n\n```\n", "parameters": [ { "in": "path", "name": "enrollment_profile_id", "description": "The ID of the enrollment profile to use for configuring the imported certificates. The enrollment profile must use the **Certificate Import** enrollment method.", "required": true, "schema": { "type": "string", "example": "IOT_88888888-4444-4444-4444-121212121212" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Object with details about the certificate import job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/importJobDetailsObject" } } } } } } }, "/v1/certificate-import/job/{job_id}": { "get": { "tags": [ "Certificates" ], "operationId": "getImportDetails", "summary": "Get import job details", "description": "Use this endpoint to get information about a certificate import job.", "parameters": [ { "$ref": "#/components/parameters/import_job_id" } ], "responses": { "200": { "description": "Object with details about the certificate import job.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/account_id" }, "division": { "$ref": "#/components/schemas/division" } } }, { "$ref": "#/components/schemas/importJobDetailsObject" } ] } } } } } } }, "/v1/certificate-status/{certificate_serial_number}": { "get": { "tags": [ "Certificates" ], "operationId": "getCertificateStatus", "summary": "Get certificate status by serial number", "description": "Use this endpoint to get the status of a certificate using the certificate's serial number.", "parameters": [ { "$ref": "#/components/parameters/certificate_serial_number" } ], "responses": { "200": { "description": "JSON object with certificate status details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/limitedCertificateDetails" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "errors": [ { "code": "entity_not_found", "message": "Certificate with ID {invalid} does not exist" } ] } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "{message}" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `VIEW_IOT_CERTIFICATE` permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } } }, "/v1/certificate-status/certificate-id/{certificate_id}": { "get": { "tags": [ "Certificates" ], "operationId": "getCertificateStatusById", "summary": "Get certificate status by ID", "description": "Use this endpoint to get the status of a certificate using the certificate's ID.", "parameters": [ { "in": "path", "required": true, "name": "certificate_id", "description": "Certificate ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "0ff3d15d-5e28-432b-8396-0503efce8dd9" } } ], "responses": { "200": { "description": "JSON object with certificate status details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/limitedCertificateDetails" } } } } } } }, "/v1/certificate/certificate-value/{certificate_value}": { "get": { "tags": [ "Certificates" ], "operationId": "listCertificatesByCertificateValue", "summary": "List certificates by certificate value", "description": "Use this endpoint to get a list of certificates with the same certificate value you provide in the request URL.\n", "parameters": [ { "$ref": "#/components/parameters/certificate_value" }, { "in": "query", "name": "limit", "description": "Number of certificates to include in the results.", "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "offset", "description": "Offset index of the first certificate to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with certificate details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of certificates with the same certificate value provided in the request URL.", "items": { "$ref": "#/components/schemas/limitedCertificateDetails" } } } } } } } } } }, "/v1/certificate/{certificate_id}/download-approved-certificate": { "post": { "summary": "Download approved certificate and private key", "operationId": "downloadApprovedCertificate", "tags": [ "Certificates" ], "description": "Use this endpoint to download the certificate for an approved enrollment or renewal request. \n\nTo authenticate to this endpoint, clients should use the same API key, passcode, or authentication certificate used to submit the enrollment or renewal request.\n\n## Response format\nThis endpoint returns your certificate data in the format you describe in the JSON request body. All request parameters are optional. Submitting an empty JSON object in your request returns a JSON object with the PEM-encoded certificate chain (end-entity, intermediate, and root certificates).\n\n### Download private keys\nIf the enrollment or renewal request used server-side keypair generation, you can use this endpoint to download both the certificate and the private key.\n\n* To get the private key, include the `private_key_format` field in your JSON request body. Requests without this parameter do not return the private key.\n\n* When a request is approved, you have thirty days to download the private key. DigiCert® IoT Trust Manager permanently deletes private keys that are not downloaded within thirty days of approving the request.\n\n* You may only download the private key once. After a successful download, DigiCert® IoT Trust Manager deletes the private key. Subsequent download requests containing the `private_key_format` field return an error.\n", "parameters": [ { "in": "path", "name": "certificate_id", "description": "ID of certificate to download", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c3783df0-caaa-4357-ae1e-63bbf4f1d46f" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "response_with_certificate_only": { "type": "boolean", "description": "If true, returns end-entity certificate data instead of a JSON object. Otherwise, false (default). For X.509 certificates, returns the PEM-encoded data for the certificate body. For GlobalPlatform certificates, returns binary data for the certificate body.\n", "example": false, "default": false }, "include_certificate_chain": { "type": "boolean", "description": "If true (default), response includes data for each certificate in the certificate chain (for example, end-entity certificate, intermediate CA certificate, and root certificate). If false, response includes data for the end-entity certificate only.\n", "example": true, "default": true }, "split_certificate_response": { "type": "boolean", "description": "If true, each certificate in the certificate chain is returned in a separate field. The `pem` field contains the end-entity certificate, and the `chain` field contains a list of objects with intermediate CA and root certificate data. If false (default), the `pem` field contains the entire certificate chain, and no `chain` array is returned.\n", "example": false, "default": false }, "private_key_format": { "type": "string", "description": "Format of private key in response. Include this parameter to download the private key for requests that used server-side keypair generation.\n\nThis parameter is only accepted if the private key is stored in DigiCert® IoT Trust Manager. Including this parameter in your request causes the API to return an error if the enrollment or renewal request used client-side keypair generation, or if the private key has already been downloaded.\n\nRequests with a `private_key_format` of `cert_encrypted` or `cert_encrypted_key_only` must include an encryption certificate (`encryption_certificate`).\n\nPossible values:\n\n* `pem`: PEM format. If `response_with_certificate_only` is true, response content type is `application/x-pem-file`.\n* `pkcs_12`: PKCS12 format. Requests using this format must include a password (`pkcs12_password`) that will protect access to the PKCS12 file. If `response_with_certificate_only` is true, response content type is `application/x-pkcs12`.\n* `cert_encrypted`: Compressed archive (ZIP) containing private key, end-entity certificate, and certificate chain (if `include_certificate_chain` is true). DigiCert encrypts the ZIP file using the `encryption_certificate` you provide in your request. If `response_with_certificate_only` is true, response content type is `application/pkcs7-mime`.\n* `cert_encrypted_key_only`: Encrypted private key only. DigiCert encrypts the private key using the `encryption_certificate` you provide in your request.\n\nFor more information about private key formats, see [Request a certificate with server-side keypair generation](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/request-certificate-with-server-side-keypair-generation.html).\n", "example": "pem", "enum": [ "pem", "pkcs_12", "cert_encrypted", "cert_encrypted_key_only" ] }, "pkcs12_password": { "type": "string", "description": "Password that protects the PKCS12 file containing the private key. Required if the value of the `private_key_format` parameter is `pkcs_12`; otherwise, ignored. Must be between 6-20 characters long. Allowed characters: A-Z, a-z, 0-9.\n", "example": "p1w9r0d" }, "encryption_certificate": { "type": "string", "description": "End-entity certificate DigiCert® IoT Trust Manager uses to encrypt the private key. Required if the value of the `private_key_format` parameter is `cert_encrypted`; otherwise, ignored. Provide the certificate in PEM format as a single string with newline characters (`\\n`) between each new line. Include the header (`-----BEGIN CERTIFICATE-----`) and footer (`-----END CERTIFICATE-----`). Use this certificate to decrypt the returned private key.\n", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" } } }, "examples": { "noPrivateKey": { "summary": "Download certificate without private key", "value": { "response_with_certificate_only": false, "split_certificate_response": true, "include_certificate_chain": true } }, "serverSidePEM": { "summary": "Download certificate and private key in PEM format", "value": { "private_key_format": "PEM", "response_with_certificate_only": false, "split_certificate_response": true, "include_certificate_chain": true } }, "serverSidePKCS12": { "summary": "Download certificate and private key in PKCS12 format", "value": { "private_key_format": "pkcs_12", "response_with_certificate_only": false, "split_certificate_response": true, "include_certificate_chain": true, "pkcs12_password": "password" } }, "serverSideCertEncrypted": { "summary": "Download certificate-encrypted certificate and private key", "value": { "private_key_format": "cert_encrypted", "response_with_certificate_only": false, "split_certificate_response": true, "include_certificate_chain": true, "encryption_certificate": "-----BEGIN CERTIFICATE-----\n......\n-----END CERTIFICATE-----" } } } } } }, "responses": { "200": { "description": "Certificate data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentResponseObject" }, "examples": { "clientSideDefault": { "$ref": "#/components/examples/clientSideDefault" }, "clientSideWithoutChain": { "$ref": "#/components/examples/clientSideWithoutChain" }, "clientSideSplitCertificateResponse": { "$ref": "#/components/examples/clientSideSplitCertificateResponse" }, "serverSidePEM": { "$ref": "#/components/examples/serverSidePEM" }, "serverSidePKCS12": { "$ref": "#/components/examples/serverSidePKCS12" }, "serverSideCertEncrypted": { "$ref": "#/components/examples/serverSideCertEncrypted" } } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" }, "examples": { "Encrypted ZIP file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `cert_encrypted`, the response is an encrypted ZIP file. The content-type is `application/pkcs7-mime`.\n" } } }, "application/x-pkcs12": { "schema": { "type": "string", "format": "binary" }, "examples": { "PFX file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pkcs_12`, the response is a PFX file. The content-type is `application/x-pkcs12`.\n" } } }, "application/x-pem-file": { "schema": { "type": "string" }, "examples": { "PEM file": { "description": "If the request uses server-side keypair generation with a `private_key_format` value of `pem`, the response is a PEM file. The content-type is `application/x-pem-file`.\n", "value": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "400 (Bad Request). The certificate enrollment or renewal request used client-side keypair generation, or the private key has already been downloaded and is no longer stored in DigiCert® IoT Trust Manager.", "value": { "errors": [ { "code": "invalid_input", "message": "Private key is not available for download" } ] } } } } } } } } }, "/v1/certificate-request/{certificate_request_id}/status": { "get": { "tags": [ "Certificate requests" ], "operationId": "getRequestStatus", "summary": "Get certificate request status", "description": "Use this endpoint to get the status of the certificate request with the given ID.\n\nTo authenticate to this endpoint, clients should use the same API key, passcode, or authentication certificate used to submit the enrollment or renewal request.\n", "parameters": [ { "in": "path", "name": "certificate_request_id", "description": "Certificate request ID.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "904a6a0a-0a5f-44f8-964f-a5aac12a76e9" } } ], "responses": { "200": { "description": "Certificate request status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate_request_id": { "description": "Certificate request ID.", "format": "uuid", "example": "ed3beb50-e2d5-4d46-9aec-342b4b5aebc9", "type": "string" }, "status": { "type": "string", "description": "Request status.", "enum": [ "PENDING_APPROVAL", "APPROVED", "AUTO_APPROVED", "REJECTED", "CANCELED" ] }, "certificate_id": { "type": "string", "description": "Certificate ID. Only returned if `status` is `APPROVED`.", "format": "uuid", "example": "51967282-23d3-429b-b4c6-a52e2c2dd389" } } }, "examples": { "pendingApproval": { "summary": "Pending approval request", "value": { "certificate_request_id": "cad89ac2-fe65-4b11-bf28-3b84a9c59bdd", "status": "PENDING_APPROVAL" } }, "approved": { "summary": "Approved request", "value": { "certificate_request_id": "cad89ac2-fe65-4b11-bf28-3b84a9c59bdd", "status": "APPROVED", "certificate_id": "b8f5aac2-b7d9-4be3-92d3-d2bdaaff3e8a" } } } } } } } } }, "/v1/division/": { "get": { "tags": [ "Divisions" ], "summary": "List divisions", "description": "Use this endpoint to get a list of divisions, or to search for divisions that meet the given search criteria.\n", "operationId": "listDivisions", "parameters": [ { "in": "query", "name": "name", "description": "Limits results to divisions with a name that contains the given string.\n", "schema": { "type": "string", "example": "Division name" } }, { "in": "query", "name": "account_id", "description": "Limits results to divisions assigned to an account ID that is an exact match for the given ID.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "status", "description": "Limits results to divisions with the given status. By default, deleted divisions do not appear in the results. To search for deleted divisions, use `status=DELETED`.", "schema": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. Default `sort_by` property is `created_at`.\n", "schema": { "type": "string" } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive. Default `sort_direction` value is `DESC`.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 1000, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with division details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of divisions.", "items": { "$ref": "#/components/schemas/divisionResponse" } } } } } } } } }, "post": { "tags": [ "Divisions" ], "operationId": "createDivision", "summary": "Create division", "description": "Use this endpoint to create a new division.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "account_id" ], "properties": { "name": { "type": "string", "description": "Unique division name.", "example": "Example division name" }, "description": { "type": "string", "description": "Custom division description.", "example": "Example division description." }, "account_id": { "$ref": "#/components/schemas/account_id" } } } } } }, "responses": { "201": { "description": "Object with division details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/divisionResponse" } } } } } } }, "/v1/division/{division_id}": { "get": { "tags": [ "Divisions" ], "summary": "Get division", "description": "Use this endpoint to get information about the given division.\n", "operationId": "getDivision", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "responses": { "200": { "description": "Object with division details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/divisionResponse" } } } } } }, "put": { "tags": [ "Divisions" ], "operationId": "updateDivision", "summary": "Update division", "description": "Use this endpoint to update the name or description of an existing division.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Unique division name.", "example": "Example division name" }, "description": { "type": "string", "description": "Custom division description.", "example": "Example division description." } } } } } }, "responses": { "200": { "description": "Object with division details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/divisionResponse" } } } } } } }, "/v1/division/{division_id}/disable": { "put": { "tags": [ "Divisions" ], "operationId": "disableDivision", "summary": "Disable division", "description": "Use this endpoint to disable a division.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "responses": { "204": { "description": "Division disabled. No content." } } } }, "/v1/division/{division_id}/enable": { "put": { "tags": [ "Divisions" ], "operationId": "enableDivision", "summary": "Enable division", "description": "Use this endpoint to enable a disabled a division.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "responses": { "204": { "description": "Division enabled. No content." } } } }, "/v1/division/{division_id}/delete": { "put": { "tags": [ "Divisions" ], "operationId": "deleteDivision", "summary": "Delete division", "description": "Use this endpoint to delete a division. Deleted divisions do not appear in search results on the **List divisions** endpoint with the default `status` filter. To search for deleted divisions, use the query parameter `status=DELETED`.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "responses": { "204": { "description": "Division deleted. No content." } } } }, "/v1/division/{division_id}/undelete": { "put": { "tags": [ "Divisions" ], "operationId": "restoreDivision", "summary": "Restore division", "description": "Use this endpoint to restore a deleted division.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "responses": { "204": { "description": "Division restored. No content." } } } }, "/v1/division/{division_id}/users/assign": { "put": { "tags": [ "Divisions" ], "operationId": "assignDivisionUsers", "summary": "Assign users to division", "description": "Use this endpoint to assign users to a division. User IDs are sourced from DigiCert® Account Manager.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "List of one or more users to assign to the division.", "items": { "type": "string", "description": "User ID (UUID).", "format": "uuid", "example": "ed27049e-b9b0-402b-bffe-e83f08605d8b" } } } } }, "responses": { "204": { "description": "Users assigned. No content." } } } }, "/v1/division/{division_id}/users": { "get": { "tags": [ "Divisions" ], "operationId": "listDivisionUsers", "summary": "List user assignments", "description": "Use this endpoint to get a list of users assigned to the given division.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 1000, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with details about each user assigned to the division.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of users assigned to the division.", "items": { "type": "object", "description": "Object with user details.", "properties": { "id": { "type": "string", "description": "User ID (UUID).", "example": "4fc4dfd5-5cbc-46e6-8360-4a2bb0c5019a" }, "full_name": { "type": "string", "description": "User full name.", "example": "Jane Doe" }, "email": { "type": "string", "description": "User email address.", "example": "jane.doe@example.com" }, "active": { "type": "boolean", "description": "If true, the user is active. Otherwise, false." }, "user_type": { "type": "string", "description": "User type.", "enum": [ "standard", "service" ] } } } } } } } } } } } }, "/v1/division/{division_id}/users/remove": { "put": { "tags": [ "Divisions" ], "operationId": "removeDivisionUsers", "summary": "Remove users from division", "description": "Use this endpoint to remove users from a division.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "List of one or more users to remove from the division.", "items": { "type": "string", "description": "User ID (UUID).", "format": "uuid", "example": "ed27049e-b9b0-402b-bffe-e83f08605d8b" } } } } }, "responses": { "204": { "description": "Users removed. No content." } } } }, "/v1/division/{division_id}/ica/assign": { "put": { "tags": [ "Divisions" ], "summary": "Assign ICAs to division", "description": "Use this endpoint to assign ICAs to a division. ICA IDs are sourced from DigiCert® CA Manager.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "List of one or more ICAs to assign to the division.", "items": { "type": "string", "description": "ICA ID (UUID).", "format": "uuid", "example": "ed27049e-b9b0-402b-bffe-e83f08605d8b" } } } } }, "responses": { "204": { "description": "ICAs assigned. No content." } } } }, "/v1/division/{division_id}/ica/remove": { "put": { "tags": [ "Divisions" ], "summary": "Remove ICAs from division", "description": "Use this endpoint to remove ICAs from a division.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string", "example": "7001eec2-25b0-49f8-a59c-dd4d92a55247" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "List of one or more ICAs to remove from the division.", "items": { "type": "string", "description": "ICA ID (UUID).", "format": "uuid", "example": "ed27049e-b9b0-402b-bffe-e83f08605d8b" } } } } }, "responses": { "204": { "description": "ICAs removed. No content." } } } }, "/v1/division/{division_id}/ica": { "get": { "tags": [ "Divisions" ], "summary": "List division ICA assignments", "description": "Use this endpoint to get a list of ICAs assigned to the given division.\n", "parameters": [ { "in": "path", "required": true, "name": "division_id", "description": "Division ID (UUID).", "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "common_name", "description": "Limits results to ICAs with the given common name.\n", "schema": { "type": "string", "example": "ICA common name" } }, { "in": "query", "name": "issuer_common_name", "description": "Limits results to ICAs issued by the given CA certificate.\n", "schema": { "type": "string", "example": "Issuer common name" } }, { "in": "query", "name": "serial_number", "description": "Limits results to ICAs with the given serial number.\n", "schema": { "type": "string", "example": "" } }, { "in": "query", "name": "status", "description": "Limits results to ICAs with the given status.\n", "schema": { "type": "string", "example": "" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to ICAs used in the given enrollment profile (UUID).\n", "schema": { "type": "string", "format": "uuid", "example": "a21cc3b4-4ee7-4d50-ab0c-484633804217" } }, { "in": "query", "name": "valid_from_from", "description": "Limits results to ICAs with a `valid_from` value on or after the given date or date-time. Use with `valid_from_to` to search for ICAs with a `valid_from` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_from_to", "description": "Limits results to ICAs with a `valid_from` value on or before the given date or date-time. Use with `valid_from_from` to search for ICAs with a `valid_from` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_to_from", "description": "Limits results to ICAs with a `valid_to` value on or after the given date or date-time. Use with `valid_to_to` to search for ICAs with a `valid_to` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_to_to", "description": "Limits results to ICAs with a `valid_to` value on or before the given date or date-time. Use with `valid_to_from` to search for ICAs with a `valid_to` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. If not provided, results are sorted in descending order by date created (`created_at`).\n", "schema": { "type": "string" } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20, "example": 1 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with details about each ICA assigned to the division.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of ICAs.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ICA ID.", "example": "01777FAA99199EFF90981078994EDD91" }, "common_name": { "type": "string", "description": "ICA common name.", "example": "Issuing ICA name" }, "organization": { "type": "string", "description": "ICA organization.", "example": "ICA organization name" }, "key_type": { "type": "string", "description": "ICA key type.", "example": "RSA 2048" }, "signature_algorithm": { "type": "string", "description": "Signature algorithm used to sign ICA.", "example": "sha256WithRSA" }, "issuer_common_name": { "type": "string", "description": "Common name of the issuing certificate for the ICA.", "example": "Issuer common name" }, "body": { "type": "string", "description": "PEM-encoded ICA certificate data.", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n" }, "valid_from": { "type": "string", "format": "date", "description": "Start date of the ICA validity period (UTC). Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2021-06-09T13:54:07Z" }, "valid_to": { "type": "string", "format": "date", "description": "End date of the ICA validity period (UTC). Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2051-06-09T13:06:23Z" }, "serial_number": { "type": "string", "description": "ICA serial number.", "example": "" }, "thumbprint": { "type": "string", "description": "ICA's calculated sha256 thumbprint.", "example": "" }, "status": { "type": "string", "description": "ICA status.", "example": "ACTIVE" }, "chain": { "$ref": "#/components/schemas/chain" } } } } } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/batch-enroll": { "post": { "tags": [ "Batch certificate enrollment" ], "summary": "Create batch enrollment job (client-side keypair generation)", "description": "Use this endpoint to create a batch certificate enrollment job from one or more certificate signing requests (CSRs). Upload your CSRs using one of these formats:\n* Compressed ZIP of CSR files for each certificate request.\n* Compressed ZIP of CSV file with details about each certificate request. \n **Note:** For client-side keypair generation, CSV files must have a `csr` column with PEM-encoded CSR data for each certificate request. [Learn how to format a CSV file for batch certificate enrollment](https://dev.digicert.com/en/digicert-one-apis/iot-trust-manager-api/csv-format-for-batch-certificate-enrollment.html). \n\nDigiCert® IoT Trust Manager processes batch enrollment jobs asynchronously in the order they are received. When the job is complete:\n1. [Download the batch enrollment job report](#/Batch%20certificate%20enrollment/downloadReport).\n1. [Approve the batch enrollment job](#/Batch%20certificate%20enrollment/approveJob).\n1. [Download your certificates](#/Batch%20certificate%20enrollment/downloadCertificates). \n\n**Requirements and limitations**\n\n- The batch enrollment method (`BATCH`) must be enabled for the enrollment profile in the request URL (`enrollment_profile_id`).\n- The ZIP file you upload cannot be larger than 200 MB.\n\n**Notes on request format**\n\n- Set the `Content-Type` header to `multipart/form-data`.\n- Use the `input_format` field to specify the format of your CSRs (`csr` or `csv`). \n- Use the `data` field to upload the compressed ZIP file with your CSRs.\n", "operationId": "batchCSREnroll", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Batch enrollment job details.", "required": [ "certificate_format", "data", "emails" ], "properties": { "name": { "description": "Friendly name for batch enrollment job. If not provided, the batch job is named after the uploaded ZIP file.\n", "type": "string" }, "certificate_format": { "type": "string", "description": "File format of certificate output.\n", "enum": [ "PEM", "DER", "JSON" ] }, "data": { "type": "string", "format": "binary", "description": "ZIP file containing CSRs for each certificate you want to enroll. Must be smaller than 200 MB.\n" }, "emails": { "$ref": "#/components/schemas/emails" }, "description": { "$ref": "#/components/schemas/description" }, "external_emails": { "$ref": "#/components/schemas/external_emails" }, "passcode_generation_option": { "$ref": "#/components/schemas/passcode_generation_option" }, "passcode": { "$ref": "#/components/schemas/passcode" }, "input_format": { "type": "string", "example": "csr", "description": "File format of CSRs in the `data` field. Allowed values:\n- `csr`: Default. Compressed ZIP of CSR files for each certificate request.\n- `csv`: Compressed ZIP of CSV file with details about each certificate request. \n", "enum": [ "csr", "csv" ] }, "report_format": { "type": "string", "example": "csv", "description": "The format for the batch log report.\n\nAllowed values:\n- `csv`\n- `json`\n", "enum": [ "csv", "json" ] }, "include_batch_report": { "type": "boolean", "example": true, "description": "When set to true, a complete results file will be generated and included in the download." } } } } } }, "responses": { "200": { "description": "Object with information about the batch enrollment job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batchEnrollmentJobResponse" } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/batch-enroll-key-gen": { "post": { "tags": [ "Batch certificate enrollment" ], "summary": "Create batch enrollment job from CSV file (server-side keypair generation)", "description": "Use this endpoint to create a batch enrollment job from a CSV file with details about each certificate request. When you submit your request, you upload the CSV in a compressed ZIP file. When the job is complete, DigiCert® IoT Trust Manager generates the keypairs and provides download access to an encrypted ZIP file containing the private keys and issued certificates.\n\nDigiCert® IoT Trust Manager processes batch enrollment jobs asynchronously in the order they are received. When the job is complete:\n1. [Download the batch enrollment job report](#/Batch%20certificate%20enrollment/downloadReport).\n1. [Approve the batch enrollment job](#/Batch%20certificate%20enrollment/approveJob).\n1. [Download your certificates](#/Batch%20certificate%20enrollment/downloadCertificates). \n\n**Requirements and limitations**\n\n- The batch enrollment method (`BATCH`) must be enabled for the enrollment profile in the request URL (`enrollment_profile_id`).\n- The enrollment profile must allow server-side keypair generation.\n- The ZIP file you upload cannot be larger than 200 MB.\n\n**Notes on request format**\n\n- Set the `Content-Type` header to `multipart/form-data`.\n- For the `data` field, upload a compressed ZIP file containing a CSV with information about each certificate you want to enroll.\n- For the `certificate` field, include the PEM-encoded text string for the certificate that will encrypt the returned ZIP file. This certificate must be registered as an authentication certificate in DigiCert® Account Manager.\n", "operationId": "batchEnrollWithKeyGen", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Details about the batch enrollment job.", "required": [ "certificate_format", "data", "emails", "key_type", "certificate" ], "properties": { "name": { "description": "Friendly name for batch enrollment job. If not provided, the batch job is named after the uploaded ZIP file.\n", "type": "string" }, "certificate_format": { "type": "string", "description": "File format of certificate output.\n\nAllowed values:\n- `PEM`\n- `DER`\n- `JSON`\n", "enum": [ "PEM", "DER", "JSON" ] }, "private_key_format": { "type": "string", "example": "pem", "description": "The format of the private key.\n\nAllowed values:\n- `pem`\n- `der`\n", "enum": [ "pem", "der" ] }, "private_key_syntax": { "type": "string", "example": "sec1_or_pkcs1", "description": "The syntax of the private key.\n\nAllowed values:\n- `sec1_or_pkcs1`\n- `pkcs8`\n", "enum": [ "sec1_or_pkcs1", "pkcs8" ] }, "report_format": { "type": "string", "example": "csv", "description": "The format for the batch log report.\n\nAllowed values:\n- `csv`\n- `json`\n", "enum": [ "csv", "json" ] }, "include_batch_report": { "type": "boolean", "description": "When set to true, a complete results file will be generated and included in the download." }, "data": { "type": "string", "format": "binary", "description": "ZIP file containing CSV with information about each certificate request in the batch enrollment job. Must be smaller than 200 MB.\n" }, "emails": { "$ref": "#/components/schemas/emails" }, "key_type": { "type": "string", "description": "Key type to use for keypair generation. Must be an allowed key type in the certificate profile associated with the enrollment profile in the request. Possible values: `RSA_2048`, `RSA_3072`, `RSA_4096`, `P_256`, `P_384`, `P_512`, `ED_25519`\n", "example": "RSA_2048", "enum": [ "RSA_2048", "RSA_3072", "RSA_4096", "P_256", "P_384", "P_512", "ED_25519" ] }, "certificate": { "example": "", "type": "string", "description": "Authentication certificate (PEM-encoded) or PGP public key used to encrypt your issued certificates and private keys." }, "description": { "$ref": "#/components/schemas/description" }, "external_emails": { "$ref": "#/components/schemas/external_emails" }, "passcode_generation_option": { "$ref": "#/components/schemas/passcode_generation_option" }, "passcode": { "$ref": "#/components/schemas/passcode" }, "session_key_encryption_algorithm": { "type": "string", "example": "rsa-encrypt-oaep-sha256", "description": "Session key encryption algorithm. If no encryption algorithm is provided, the default RSA encryption PKCS1 v1.5 will be used.\n\nAllowed values:\n- `rsa-encrypt-oaep-sha256`\n", "enum": [ "rsa-encrypt-oaep-sha256" ] } } } } } }, "responses": { "200": { "description": "Object with information about the batch enrollment job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batchEnrollmentJobResponse" } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/batch-enroll-key-gen-mac": { "post": { "tags": [ "Batch certificate enrollment" ], "summary": "Create batch enrollment job from MAC addresses (server-side keypair generation)", "description": "Use this endpoint to create a batch certificate enrollment job for up to 100,000 MAC addresses. When the job is complete, DigiCert® IoT Trust Manager generates keypairs for each MAC address and provides download access to an encrypted ZIP file containing the private keys and issued certificates.\n\nDigiCert® IoT Trust Manager processes batch enrollment jobs asynchronously in the order they are received. When the job is complete:\n1. [Download the batch enrollment job report](#/Batch%20certificate%20enrollment/downloadReport).\n1. [Approve the batch enrollment job](#/Batch%20certificate%20enrollment/approveJob).\n1. [Download your certificates](#/Batch%20certificate%20enrollment/downloadCertificates). \n\n**Requirements and limitations**\n\n- The batch enrollment method (`BATCH`) must be enabled for the enrollment profile in the request URL (`enrollment_profile_id`).\n- The enrollment profile must allow server-side keypair generation.\n\n**Notes on request format**\n\n- Set the `Content-Type` header to `multipart/form-data`.\n- In the request payload, include the starting MAC address (`mac_address_from`), the number of certificates to enroll (`mac_address_number`), and the number by which to increment the MAC address for each certificate request (`mac_address_step`).\n- For the `certificate` field, include the PEM-encoded text string for the certificate that will encrypt the returned ZIP file. This certificate must be registered as an authentication certificate in DigiCert® Account Manager.\n", "operationId": "batchEnrollWithKeyGenMac", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Details about the batch enrollment job.", "required": [ "certificate_format", "emails", "key_type", "certificate", "mac_address_from", "mac_address_number", "mac_address_step" ], "properties": { "name": { "description": "Friendly name for batch enrollment job. If not provided, the batch job is named after the `mac_address_from` value. For example: `MAC `.\n", "type": "string" }, "certificate_format": { "type": "string", "description": "File format of certificate output.\n\nAllowed values:\n- `PEM`\n- `DER`\n- `JSON`\n", "enum": [ "PEM", "DER", "JSON" ] }, "private_key_format": { "type": "string", "example": "pem", "description": "The format of the private key.\n\nAllowed values:\n- `pem`\n- `der`\n", "enum": [ "pem", "der" ] }, "private_key_syntax": { "type": "string", "example": "sec1_or_pkcs1", "description": "The syntax of the private key.\n\nAllowed values:\n- `sec1_or_pkcs1`\n- `pkcs8`\n", "enum": [ "sec1_or_pkcs1", "pkcs8" ] }, "report_format": { "type": "string", "example": "csv", "description": "The format for the batch log report.\n\nAllowed values:\n- `csv`\n- `json`\n", "enum": [ "csv", "json" ] }, "mac_address_from": { "type": "string", "example": "10:20:30:40:50:60", "description": "Starting MAC address. Format: `XX:XX:XX:XX:XX:XX` or `XX-XX-XX-XX-XX-XX`\n" }, "mac_address_number": { "type": "integer", "example": 10, "description": "Number of certificates to request." }, "mac_address_step": { "type": "integer", "example": 10, "description": "Number to increment each MAC address by." }, "emails": { "$ref": "#/components/schemas/emails" }, "key_type": { "type": "string", "description": "Key type to use for keypair generation. Must be an allowed key type in the certificate profile associated with the enrollment profile in the request. Possible values: `RSA_2048`, `RSA_3072`, `RSA_4096`, `P_256`, `P_384`, `P_512`, `ED_25519`\n", "example": "RSA_2048", "enum": [ "RSA_2048", "RSA_3072", "RSA_4096", "P_256", "P_384", "P_512", "ED_25519" ] }, "certificate": { "example": "", "type": "string", "description": "Authentication certificate (PEM-encoded) or PGP public key used to encrypt your issued certificates and private keys." }, "description": { "$ref": "#/components/schemas/description" }, "external_emails": { "$ref": "#/components/schemas/external_emails" }, "passcode_generation_option": { "$ref": "#/components/schemas/passcode_generation_option" }, "passcode": { "$ref": "#/components/schemas/passcode" }, "include_batch_report": { "type": "boolean", "example": true, "description": "When set to true, a complete results file will be generated and included in the download." }, "session_key_encryption_algorithm": { "type": "string", "example": "rsa-encrypt-oaep-sha256", "description": "Session key encryption algorithm. If no encryption algorithm is provided, the default RSA encryption PKCS1 v1.5 will be used.\n\nAllowed values:\n- `rsa-encrypt-oaep-sha256`\n", "enum": [ "rsa-encrypt-oaep-sha256" ] } } } } } }, "responses": { "200": { "description": "Object with information about the batch enrollment job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batchEnrollmentJobResponse" } } } } } } }, "/v1/batch-enroll": { "get": { "tags": [ "Batch certificate enrollment" ], "summary": "List batch enrollment jobs", "description": "Use this endpoint to list batch enrollment jobs in your account.\n", "operationId": "listBatchJobs", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to batch enrollment jobs for the account with the given ID.\n", "schema": { "type": "string", "format": "uuid", "example": "35f4c985-4480-4ade-93c7-c9cd178b1133" } }, { "in": "query", "name": "division_id", "description": "Limits results to batch enrollment jobs for the division with the given ID.\n", "schema": { "type": "string", "format": "uuid", "example": "58fc85a3-5a1d-4626-8633-5452a478034f" } }, { "in": "query", "name": "statuses", "description": "Limits results to batch enrollment jobs with one of the given statuses. Accepts a comma-separated list of one or more statuses.\n", "schema": { "type": "string", "example": "PENDING,IN_PROGRESS", "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED", "PENDING_APPROVAL", "APPROVED", "REJECTED", "FAILED", "WAIT_FOR_EXTERNAL_JOB" ] } }, { "in": "query", "name": "name", "description": "Limits results to batch enrollment jobs with a name that contains the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "example_name" } }, { "in": "query", "name": "file_name", "description": "Limits results to batch enrollment jobs created from a file with a name (`file_name`) that contains the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "batch_upload_file" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to batch enrollment jobs for the enrollment profile with the given ID.", "schema": { "type": "string", "example": "2953d4a7-883b-4b6c-a865-f78f1bc64490", "format": "uuid" } }, { "in": "query", "name": "created_at_from", "description": "Limits results to batch enrollment jobs created **after** the given date and time (UTC). Use with `created_at_to` to search for credentials with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "created_at_to", "description": "Limits results to batch enrollment jobs created **before** the given date and time (UTC). Use with `created_at_from` to search for credentials with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "requested_by_id", "description": "Limits results to batch enrollment jobs requested by the user with the given ID.", "schema": { "type": "string", "example": "2953d4a7-883b-4b6c-a865-f78f1bc64490", "format": "uuid" } }, { "in": "query", "name": "approved_by_id", "description": "Limits results to batch enrollment jobs approved by the user with the given ID.", "schema": { "type": "string", "example": "2953d4a7-883b-4b6c-a865-f78f1bc64490", "format": "uuid" } }, { "in": "query", "name": "data_available", "description": "If true, limits results to batch enrollment jobs with results available for download. If false, limits results to batch enrollment jobs without results available for download.", "schema": { "type": "boolean", "example": true } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "type": "string", "default": "created_at", "enum": [ "name", "account_id", "division_id", "created_at", "status" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "default": "DESC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of batch enrollment jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Batch enrollment job ID.", "example": "a7cdd1ac-8e64-417e-80d7-c5c2d8bab0aa" }, "name": { "type": "string", "description": "Batch enrollment job friendly name.", "example": "Example batch job" }, "status": { "type": "string", "description": "Batch enrollment job status.\n\n- `PENDING`: Job submitted to processing queue.\n- `IN_PROGRESS`: Job is processing.\n- `PENDING_APPROVAL`: Job processed and ready to be approved or rejected.\n- `APPROVED`: Job approved and certificates are ready to be downloaded.\n- `REJECTED`: Job rejected.\n- `FAILED`: Job processing failed.\n", "enum": [ "PENDING", "IN_PROGRESS", "PENDING_APPROVAL", "APPROVED", "REJECTED", "FAILED" ] }, "total_items": { "type": "integer", "description": "Number of certificate requests in the batch enrollment job.", "example": 10 }, "failed_items": { "type": "integer", "description": "Number of failed certificate requests in the batch enrollment job.", "example": 0 }, "processing_time": { "type": "integer", "description": "Batch job processing time, in milliseconds.", "example": 0 }, "job_type": { "type": "string", "description": "Job type.", "example": "BATCH_CERTIFICATE_ENROLL", "enum": [ "BATCH_CERTIFICATE_ENROLL", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN_MAC", "EXTERNAL_BATCH_ENROLL" ] }, "requested_by_name": { "type": "string", "description": "Username of user that submitted the batch job request.", "example": "example.admin" }, "approved_by_name": { "type": "string", "description": "Name of individual that approved the batch job.", "example": "example.admin" }, "passcode_generation_option": { "type": "string", "enum": [ "AUTO", "PROVIDED", "NONE" ], "description": "Generation method for passcode used to access external download link. For external batch enrollment jobs, `passcode_generation_option` always returns as `NONE`.\n\n* `NONE` (default): External recipients can download certificates without providing a passcode.\n* `AUTO`: DigiCert® IoT Trust Manager generates the passcode.\n* `PROVIDED`: A user provides the passcode.\n", "example": "NONE" }, "passcode": { "type": "string", "description": "Obfuscated passcode for external download link.\n", "example": "PA*******************" }, "description": { "type": "string", "description": "Custom description for the batch enrollment job.\n", "example": "Example description." }, "certificate_format": { "type": "string", "description": "File format of certificate output.", "example": "PEM", "enum": [ "PEM", "DER" ] }, "emails": { "type": "array", "description": "Comma-separated list of email addresses for DigiCert ONE users who receive a notification email when the batch enrollment job is complete.", "items": { "type": "string" }, "example": [ "bob@example.com", "alice@example.com" ] }, "external_emails": { "type": "array", "description": "List of email addresses that receive a unique download link when the batch job is complete.\n", "example": [ "john@example.com", "jane@example.com" ], "items": { "type": "string" } }, "data_available": { "type": "boolean", "description": "If true, batch job results are available for download. Otherwise, false.\n" }, "include_full_chain_with_each_certificate": { "type": "boolean", "description": "If true, full certificate chain is included for each certificate in the batch job. Otherwise, false." }, "include_intermediates_with_each_certificate": { "type": "boolean", "description": "If true, issuing CA certificate is included for each certificate in the batch job. Otherwise, false." } } } } } } } } } } } }, "/v1/batch-enroll/{job_id}": { "get": { "tags": [ "Batch certificate enrollment" ], "operationId": "getBatchJobSettings", "summary": "Get batch enrollment job settings", "description": "Use this endpoint to get settings for the given batch enrollment job.", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "responses": { "200": { "description": "Object with information about the batch enrollment job.", "content": { "application/json": { "schema": { "type": "object", "description": "Object containing information about a batch enrollment job.", "properties": { "id": { "type": "string", "description": "Batch enrollment job ID.", "example": "e197ba9d-3af3-4012-9861-d214cce33cd8" }, "name": { "type": "string", "description": "Batch enrollment job friendly name.", "example": "Example batch job" }, "status": { "type": "string", "description": "Batch enrollment job status.\n\n- `PENDING`: Job submitted to processing queue.\n- `IN_PROGRESS`: Job is processing.\n- `PENDING_APPROVAL`: Job processed and ready to be approved or rejected.\n- `APPROVED`: Job approved and certificates are ready to be downloaded.\n- `REJECTED`: Job rejected.\n- `FAILED`: Job processing failed.\n", "enum": [ "PENDING", "IN_PROGRESS", "PENDING_APPROVAL", "APPROVED", "REJECTED", "FAILED" ] }, "total_items": { "type": "integer", "description": "Number of certificate requests in the batch enrollment job.", "example": 10 }, "failed_items": { "type": "integer", "description": "Number of failed certificate requests in the batch enrollment job.", "example": 0 }, "processing_time": { "type": "integer", "description": "Batch job processing time, in milliseconds.", "example": 900 }, "job_type": { "type": "string", "description": "Job type.", "example": "BATCH_CERTIFICATE_ENROLL", "enum": [ "BATCH_CERTIFICATE_ENROLL", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN_MAC" ] }, "passcode": { "type": "string", "minLength": 6, "maxLength": 20, "description": "Obfuscated passcode for external download link.\n", "example": "PA*******************" }, "passcode_generation_option": { "type": "string", "enum": [ "AUTO", "PROVIDED", "NONE" ], "description": "Generation method for passcode used to access external download link.\n\n* `NONE` (default): External recipients can download certificates without providing a passcode.\n* `AUTO`: DigiCert® IoT Trust Manager generates the passcode.\n* `PROVIDED`: A user provides the passcode.\n", "example": "AUTO" }, "description": { "type": "string", "description": "Custom description for the batch enrollment job.\n", "example": "Example description." }, "certificate_format": { "type": "string", "description": "File format of certificate output.\n", "enum": [ "PEM", "DER", "JSON" ], "example": "PEM" }, "emails": { "type": "array", "description": "Comma-separated list of email addresses for DigiCert ONE users who receive a notification email when the batch enrollment job is complete.", "items": { "type": "string" }, "example": [ "bob@example.com", "alice@example.com" ] }, "external_emails": { "type": "array", "description": "List of email addresses that receive a unique download link when the batch job is complete.\n", "example": [ "john@example.com", "jane@example.com" ], "items": { "type": "string" } }, "data_available": { "type": "boolean", "description": "If true, batch job results are available for download. Otherwise, false. **Note:** Batch job results remain available for 30 days after the job completes. You can still download individual certificates after the batch job itself is removed.\n" } } } } } } } }, "put": { "tags": [ "Batch certificate enrollment" ], "operationId": "updateBatchJobSettings", "summary": "Update batch enrollment job settings", "description": "Use this endpoint to update settings for the given batch enrollment job.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Batch enrollment job settings.", "properties": { "name": { "description": "Friendly name for batch enrollment job.\n", "type": "string" }, "emails": { "$ref": "#/components/schemas/emails" }, "description": { "$ref": "#/components/schemas/description" }, "external_emails": { "$ref": "#/components/schemas/external_emails" }, "passcode_generation_option": { "type": "string", "enum": [ "AUTO", "PROVIDED", "NONE" ], "description": "Generation method for passcode used to access external download link. Use this field to require a passcode from external recipients (`external_emails`) when downloading batch certificates. Updating a batch enrollment job to require a passcode means external recipients who have not already downloaded the batch job will need to provide a passcode to access the download.\n\n* `NONE` (default): External recipients can download certificates without providing a passcode.\n* `AUTO`: DigiCert® IoT Trust Manager generates a passcode for you. Using `AUTO` in requests to update batch job settings only generates a new passcode when changing to `AUTO` from another generation method. To change the passcode for a batch job already using `AUTO`, use the **Regenerate passcode** endpoint.\n* `PROVIDED`: Provide your own passcode in the `passcode` request parameter.\n" }, "passcode": { "type": "string", "minLength": 6, "maxLength": 20, "description": "Passcode for external download link. Must be between 6 and 20 characters. **Note:** When changing the `passcode_generation_option` to `PROVIDED` from one of the other methods, you must provide a `passcode` value.\n" } } } } } }, "responses": { "200": { "description": "Object with information about the batch enrollment job.", "content": { "application/json": { "schema": { "type": "object", "description": "Object containing information about a batch enrollment job.", "properties": { "id": { "type": "string", "description": "Batch enrollment job ID.", "example": "42dbf316-6618-4ab2-9770-5ce7e0c9d62c" }, "name": { "type": "string", "description": "Batch enrollment job friendly name.", "example": "Example batch job" }, "status": { "type": "string", "description": "Batch enrollment job status.\n\n- `PENDING`: Job submitted to processing queue.\n- `IN_PROGRESS`: Job is processing.\n- `PENDING_APPROVAL`: Job processed and ready to be approved or rejected.\n- `APPROVED`: Job approved and certificates are ready to be downloaded.\n- `REJECTED`: Job rejected.\n- `FAILED`: Job processing failed.\n", "enum": [ "PENDING", "IN_PROGRESS", "PENDING_APPROVAL", "APPROVED", "REJECTED", "FAILED" ] }, "total_items": { "type": "integer", "description": "Number of certificate requests in the batch enrollment job.", "example": 10 }, "failed_items": { "type": "integer", "description": "Number of failed certificate requests in the batch enrollment job.", "example": 0 }, "processing_time": { "type": "integer", "description": "Batch job processing time, in milliseconds.", "example": 900 }, "job_type": { "type": "string", "description": "Job type.", "example": "BATCH_CERTIFICATE_ENROLL", "enum": [ "BATCH_CERTIFICATE_ENROLL", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN_MAC" ] }, "passcode": { "type": "string", "minLength": 6, "maxLength": 20, "description": "Passcode for external download link. Omitted if no passcode exists. **Note:** When the value of `passcode_generation_option` is `AUTO`, DigiCert® IoT Trust Manager only returns the full passcode once, when the passcode is created. Otherwise, we only return the first two characters of the passcode and obfuscate the rest.\n", "example": "PA*******************" }, "passcode_generation_option": { "type": "string", "enum": [ "AUTO", "PROVIDED", "NONE" ], "description": "Generation method for passcode used to access external download link.\n\n* `NONE` (default): External recipients can download certificates without providing a passcode.\n* `AUTO`: DigiCert® IoT Trust Manager generates the passcode.\n* `PROVIDED`: A user provides the passcode.\n", "example": "AUTO" }, "description": { "type": "string", "description": "Custom description for the batch enrollment job. Omitted if no description exists.\n", "example": "Example description." }, "certificate_format": { "type": "string", "description": "File format of certificate output.\n", "enum": [ "PEM", "DER", "JSON" ], "example": "PEM" }, "emails": { "type": "array", "description": "Comma-separated list of email addresses for DigiCert ONE users who receive a notification email when the batch enrollment job is complete.", "items": { "type": "string" }, "example": [ "bob@example.com", "alice@example.com" ] }, "external_emails": { "type": "array", "description": "List of email addresses that receive a unique download link when the batch job is complete.\n", "example": [ "john@example.com", "jane@example.com" ], "items": { "type": "string" } }, "data_available": { "type": "boolean", "description": "If true, batch job results are available for download. Otherwise, false. **Note:** Batch job results remain available for 30 days after the job completes. You can still download individual certificates after the batch job itself is removed.\n" } } } } } } } } }, "/v1/batch-enroll/{jobId}/regenerate-passcode": { "put": { "tags": [ "Batch certificate enrollment" ], "operationId": "regenerateBatchJobPasscode", "summary": "Regenerate passcode", "description": "Use this endpoint to regenerate the passcode external users must provide to download a batch job. In the response, the `passcode` field returns the new passcode value.\n\n**Note:** To use this endpoint, the given batch enrollment job must have a `passcode_generation_option` of `AUTO`.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "responses": { "200": { "description": "Object with information about the batch enrollment job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batchEnrollmentJobResponse" } } } } } } }, "/v1/batch-enroll/{job_id}/approve": { "put": { "tags": [ "Batch certificate enrollment" ], "operationId": "approveJob", "summary": "Approve batch enrollment job", "description": "Use this endpoint to approve a batch certificate enrollment job. You must approve a job before you can download the issued certificates and private keys. Only jobs with a status of `PENDING_APPROVAL` can be approved or rejected.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "responses": { "204": { "description": "No content" } } } }, "/v1/batch-enroll/{job_id}/reject": { "put": { "tags": [ "Batch certificate enrollment" ], "operationId": "rejectJob", "summary": "Reject batch enrollment job", "description": "Use this endpoint to reject the results of a batch certificate enrollment job. Rejected jobs remain in DigiCert® , but the issued certificates and keys can never be downloaded. Only jobs with a status of `PENDING_APPROVAL` can be approved or rejected.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rejection_reason": { "type": "string", "description": "Custom rejection reason. Character limit: 255\n" } } } } } }, "responses": { "204": { "description": "No content" } } } }, "/v1/batch-enroll/{job_id}/download-report": { "get": { "tags": [ "Batch certificate enrollment" ], "operationId": "downloadReport", "summary": "Download batch certificate enrollment report", "description": "Use this endpoint to download a report with information about a completed batch enrollment job. To download a report, the job must have a status of `PENDING_APPROVAL`, `FAILED`, `APPROVED`, or `REJECTED`.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "responses": { "200": { "description": "Compressed ZIP file containing CSV-formatted report", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/v1/batch-enroll/{job_id}/download-certificates": { "get": { "operationId": "downloadCertificates", "tags": [ "Batch certificate enrollment" ], "summary": "Download certificates", "description": "Use this endpoint to download the certificates issued from a completed batch enrollment job. Only jobs with a status of `APPROVED` can be downloaded.\n\n## Response format\n\nThe Content-Type of the API response depends on two factors:\n* Keypair generation method (client-side or server-side)\n\n* Certificate format (JSON, PEM, or DER)\n\n### Client-side keypair generation\n\n* **PEM/DER**: If the `certificate_format` is `PEM` or `DER`, the Content-Type header in the API response is `application/zip`. The download is a compressed ZIP file with the issued certificates.\n\n* **JSON**: If the `certificate_format` is `JSON`, the Content-Type header in the API response is `application/json`. The JSON response contains a list of `certificate` objects with the issued certificates.\n\n### Server-side keypair generation\n\n* **PEM/DER**: If the `certificate_format` is `PEM` or `DER`, the Content-Type header in the API response is `application/pkcs7-mime`. Decrypt this P7M file to access a compressed ZIP file with the issued certificates and generated private keys. To decrypt the P7M file, use the private key for the authentication certificate that was included in the request to create the batch enrollment job. For example, to decrypt the P7M file using OpenSSL, run the following command in your terminal or command prompt:\n\n openssl smime -binary -decrypt -aes256 -inform DER -in .p7m -out .zip -inkey .pem .pem \n\n* **JSON**: If the `certificate_format` is `JSON`, the Content-Type header in the API response is `application/json`. The JSON response contains a list of `certificate` objects with the issued certificates and encrypted private keys.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "responses": { "200": { "description": "Downloaded file", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "properties": { "job_id": { "description": "Batch job ID.", "example": "04fa5382-00e0-4322-813d-fcce9747d51f", "format": "uuid", "type": "string" }, "chain": { "type": "array", "description": "List of objects with details about each certificate in the issuing chain for the batch job. Each certificate in the `chain` array is signed by the certificate in the object that follows it.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "cert_type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "blob": { "type": "string", "description": "Certificate body.", "example": "MII..." }, "common_name": { "type": "string", "description": "Certificate common name.", "example": "Issuing CA name" } } } }, "certificates": { "type": "array", "description": "List of certificates and encrypted private keys.", "items": { "type": "object", "description": "Object with certificate and encrypted private key.", "properties": { "id": { "type": "string", "example": "a8a84a9c-313d-4714-a154-a46bae0a80d9", "format": "uuid", "description": "Certificate ID." }, "unique_identifier": { "description": "Certificate unique identifier.", "example": "b0-f4-a8-10-53-0f", "type": "string" }, "body": { "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----\n", "description": "End-entity certificate in PEM format." }, "private_key": { "type": "string", "description": "For batch jobs using server-side keypair generation, returns the encrypted private key. Omitted for batch jobs using client-side keypair generation.\n", "example": "" } } } } } }, "examples": { "serverSideJSONBatch": { "summary": "JSON certificates for server-side keypair generation batch", "value": { "job_id": "04fa5382-00e0-4322-813d-fcce9747d51f", "chain": [ { "cert_type": "intermediate", "blob": "MII...", "common_name": "Issuing CA name" } ], "certificates": [ { "id": "a8a84a9c-313d-4714-a154-a46bae0a80d9", "unique_identifier": "b0-f4-a8-10-53-0f", "body": "-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----\n", "private_key": "" } ] } }, "clientSideJSONBatch": { "summary": "JSON certificates for client-side keypair generation batch", "value": { "job_id": "04fa5382-00e0-4322-813d-fcce9747d51f", "chain": [ { "cert_type": "intermediate", "blob": "MII...", "common_name": "Issuing CA name" } ], "certificates": [ { "id": "a8a84a9c-313d-4714-a154-a46bae0a80d9", "unique_identifier": "b0-f4-a8-10-53-0f", "body": "-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----\n" } ] } } } } } } } } }, "/v1/batch-enroll/{job_id}/delete-download-urls": { "put": { "tags": [ "Batch certificate enrollment" ], "operationId": "deleteDownloadUrls", "summary": "Delete download URLs", "description": "Use this endpoint to delete the download URLs for the given batch enrollment job. Deleting these URLs invalidates all external download links for the batch job.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "responses": { "204": { "description": "Deletion successful (no content)." } } } }, "/v1/batch-enroll/{job_id}/resend-download-urls": { "put": { "tags": [ "Batch certificate enrollment" ], "operationId": "resendDownloadUrls", "summary": "Resend download URLs", "description": "Use this endpoint to resend the download URLs for the given batch enrollment job. This operation creates new download links and emails them to all external emails (`external_emails`) on the batch job. Prior external download links for the batch job are invalidated.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "responses": { "204": { "description": "Resend successful (no content)." } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/external-batch-enroll": { "post": { "tags": [ "External batch certificate enrollment" ], "operationId": "batchEnrollExternal", "summary": "Create external batch certificate enrollment job", "description": "Use this endpoint to submit a batch enrollment job that requests certificates from an enrollment profile in another DigiCert® IoT Trust Manager account.\n\nTo create an external batch enrollment job, upload a compressed CSV file with details about each certificate request. To learn how to format the CSV file, see [CSV format for batch certificate enrollment](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/csv-format-for-batch-certificate-enrollment.html).\n\n**Requirements and limitations**\n\n- The enrollment profile in the request URL (`enrollment_profile_id`) must have an enrollment method of `EXTERNAL_BATCH`.\n- The ZIP file you upload cannot be larger than 200 MB.\n\n**Notes on request format**\n\n- Set the `Content-Type` header to `multipart/form-data`.\n- For the `data` field, upload a compressed ZIP file containing a CSV with information about each certificate you want to enroll.\n", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Details about the batch enrollment job.", "required": [ "data", "emails" ], "properties": { "name": { "description": "Friendly name for batch enrollment job. If not provided, the batch job is named after the uploaded ZIP file.\n", "type": "string" }, "data": { "type": "string", "format": "binary", "description": "ZIP file containing CSV with information about each certificate request in the batch enrollment job. Must be smaller than 200 MB.\n" }, "emails": { "$ref": "#/components/schemas/emails" }, "key_type": { "type": "string", "description": "Key type. Provided value must be allowed by the external enrollment profile. If not provided, external enrollment profile's default key type is used. Possible values: `RSA_2048`, `RSA_3072`, `RSA_4096`, `P_256`, `P_384`, `P_512`, `ED_25519`\n", "example": "RSA_2048", "enum": [ "RSA_2048", "RSA_3072", "RSA_4096", "P_256", "P_384", "P_512", "ED_25519" ] }, "signature_algorithm": { "type": "string", "description": "Signature algorithm. Provided value must be allowed by the external enrollment profile. If not provided, external enrollment profile's default signature algorithm is used. Possible values: `sha1WithRSA`, `sha256WithRSA`, `sha384WithRSA`, `sha512WithRSA`, `sha256WithECDSA`, `sha384WithECDSA`, `sha512WithECDSA`, `sha3_256WithRSA`, `sha3_384WithRSA`, `sha3_512WithRSA`.\n", "enum": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA" ] }, "description": { "$ref": "#/components/schemas/description" }, "include_full_chain_with_each_certificate": { "type": "boolean", "example": true }, "include_intermediates_with_each_certificate": { "type": "boolean", "example": true }, "include_batch_report": { "type": "boolean", "example": true, "description": "When set to true, a complete results file will be generated and included in the download." } } } } } }, "responses": { "200": { "description": "Object with information about the batch enrollment job.", "content": { "application/json": { "schema": { "type": "object", "description": "Object containing information about a batch enrollment job.", "properties": { "id": { "type": "string", "description": "Batch enrollment job ID.", "example": "a7cdd1ac-8e64-417e-80d7-c5c2d8bab0aa" }, "name": { "type": "string", "description": "Batch enrollment job friendly name.", "example": "Example batch job" }, "status": { "type": "string", "description": "Batch enrollment job status.\n\n- `PENDING`: Job submitted to processing queue.\n- `IN_PROGRESS`: Job is processing.\n- `PENDING_APPROVAL`: Job processed and ready to be approved or rejected.\n- `APPROVED`: Job approved and certificates are ready to be downloaded.\n- `REJECTED`: Job rejected.\n- `FAILED`: Job processing failed.\n", "enum": [ "PENDING", "IN_PROGRESS", "PENDING_APPROVAL", "APPROVED", "REJECTED", "FAILED" ] }, "total_items": { "type": "integer", "description": "Number of certificate requests in the batch enrollment job.", "example": 10 }, "failed_items": { "type": "integer", "description": "Number of failed certificate requests in the batch enrollment job.", "example": 0 }, "processing_time": { "type": "integer", "description": "Batch job processing time, in milliseconds.", "example": 0 }, "job_type": { "type": "string", "description": "Job type.", "example": "BATCH_CERTIFICATE_ENROLL", "enum": [ "BATCH_CERTIFICATE_ENROLL", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN_MAC", "EXTERNAL_BATCH_ENROLL" ] }, "requested_by_name": { "type": "string", "description": "Username of user that submitted the batch job request.", "example": "example.admin" }, "passcode_generation_option": { "type": "string", "enum": [ "AUTO", "PROVIDED", "NONE" ], "description": "Generation method for passcode used to access external download link. For external batch enrollment jobs, `passcode_generation_option` always returns as `NONE`.\n\n* `NONE` (default): External recipients can download certificates without providing a passcode.\n* `AUTO`: DigiCert® IoT Trust Manager generates the passcode.\n* `PROVIDED`: A user provides the passcode.\n", "example": "NONE" }, "description": { "type": "string", "description": "Custom description for the batch enrollment job. Omitted if no description exists.\n", "example": "Example description." }, "emails": { "type": "array", "description": "Comma-separated list of email addresses for DigiCert ONE users who receive a notification email when the batch enrollment job is complete.", "items": { "type": "string" }, "example": [ "bob@example.com", "alice@example.com" ] } } } } } } } } }, "/v1/batch-enroll/{job_id}/download-mapping": { "get": { "tags": [ "External batch certificate enrollment" ], "operationId": "downloadMapping", "summary": "Download certificate ID mapping", "description": "Use this endpoint to download a CSV file with IDs for each certificate in the given external batch enrollment job. The CSV file shows the ID of the issued certificate for each unique value or line number in the file used to create the batch job.\n\n**Note:** You can only download certificate ID mapping for batch jobs created for enrollment profiles with an enrollment method of `EXTERNAL_BATCH`.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" } ], "responses": { "200": { "description": "Compressed ZIP file with CSV output .", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "description": "Compressed ZIP file with CSV output." } } } } } } }, "/v1/certificate-download/job/{job_id}/unique-identifier/{unique_identifier}/format/{format}": { "get": { "operationId": "downloadByJobIdAndUniqueId", "summary": "Download certificate by job and unique identifier", "tags": [ "External batch certificate enrollment" ], "description": "Use this endpoint to download the certificate and private key for a certificate with the given job ID and unique identifier. To use this operation, the certificate must have been issued using the `EXTERNAL_BATCH` enrollment method.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" }, { "in": "path", "name": "unique_identifier", "description": "Unique identifier for the certificate. To get the unique identifier for each certificate in a batch job, use the **Download certificate ID mapping** endpoint.", "required": true, "schema": { "example": "unique_id", "type": "string" } }, { "in": "path", "name": "format", "description": "Certificate download format (`pem` or `pkcs12`).", "required": true, "schema": { "type": "string", "example": "pem", "enum": [ "pem", "pkcs12" ] } } ], "responses": { "200": { "description": "Downloaded certificate and private key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/downloadBatchCertificateResponseObject" }, "examples": { "pkcs12": { "$ref": "#/components/examples/downloadBatchCertificatePKCS12" }, "pem": { "$ref": "#/components/examples/downloadBatchCertificatePEM" } } } } } } } }, "/v1/certificate-download/common-name/{common_name}?format=value": { "get": { "operationId": "downloadByCommonName", "summary": "Download certificate by common name. The format will default to PEM if non is specified.", "tags": [ "External batch certificate enrollment" ], "description": "Use this endpoint to download the certificate and private key for a certificate with the given common name. To use this operation, the certificate must have been issued using the `EXTERNAL_BATCH` enrollment method.\n\nThis endpoint returns multiple certificates if the common name is not unique. Responses with multiple certificates are sorted in descending order by the creation date and time of the certificate.\n", "parameters": [ { "in": "path", "name": "common_name", "description": "Common name on the certificate.", "required": true, "schema": { "example": "Example device", "type": "string" } }, { "in": "query", "name": "format", "description": "Certificate download format (`pem` or `pkcs12`).", "required": false, "schema": { "type": "string", "example": "pem", "enum": [ "pem", "pkcs12" ] } } ], "responses": { "200": { "description": "Downloaded certificates and private keys.", "content": { "application/json": { "schema": { "type": "array", "description": "List of objects with certificate data.", "items": { "$ref": "#/components/schemas/downloadBatchCertificateResponseObject" } }, "examples": { "pkcs12": { "$ref": "#/components/examples/downloadBatchCertificatePKCS12List" }, "pem": { "$ref": "#/components/examples/downloadBatchCertificatePEMList" } } } } } } } }, "/v1/certificate-download/{id}?format=value": { "get": { "operationId": "downloadById", "summary": "Download certificate by id. The format will default to PEM if non is specified.", "tags": [ "External batch certificate enrollment" ], "description": "Use this endpoint to download the certificate and private key for a certificate with the given id. To use this operation, the certificate must have been issued using the `EXTERNAL_BATCH` enrollment method.\n\nThis endpoint returns a certificate if the id is a match. Responses with a certificate.\n", "parameters": [ { "in": "path", "name": "id", "description": "Id of the certificate.", "required": true, "schema": { "example": "Example device", "type": "string" } }, { "in": "query", "name": "format", "description": "Certificate download format (`pem` or `pkcs12`).", "required": false, "schema": { "type": "string", "example": "pem", "enum": [ "pem", "pkcs12" ] } } ], "responses": { "200": { "description": "Downloaded certificates and private keys.", "content": { "application/json": { "schema": { "type": "array", "description": "List of objects with certificate data.", "items": { "$ref": "#/components/schemas/downloadBatchCertificateResponseObject" } }, "examples": { "pkcs12": { "$ref": "#/components/examples/downloadBatchCertificatePKCS12List" }, "pem": { "$ref": "#/components/examples/downloadBatchCertificatePEMList" } } } } } } } }, "/v1/certificate-download/job/{job_id}/common-name/{common_name}/format/{format}": { "get": { "operationId": "downloadByJobIdAndCommonName", "summary": "Download certificate by job ID and common name", "tags": [ "External batch certificate enrollment" ], "description": "Use this endpoint to download the certificate and private key for a certificate with the given job ID and common name. To use this operation, the certificate must have been issued using the `EXTERNAL_BATCH` enrollment method.\n\nThis endpoint returns multiple certificates if the common name is not unique. Responses with multiple certificates are sorted in descending order by the creation date and time of the certificate.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" }, { "in": "path", "name": "common_name", "description": "Common name on the certificate.", "required": true, "schema": { "example": "Example device", "type": "string" } }, { "in": "path", "name": "format", "description": "Certificate download format (`pem` or `pkcs12`).", "required": true, "schema": { "type": "string", "example": "pem", "enum": [ "pem", "pkcs12" ] } } ], "responses": { "200": { "description": "Downloaded certificates and private keys.", "content": { "application/json": { "schema": { "type": "array", "description": "List of objects with certificate data.", "items": { "$ref": "#/components/schemas/downloadBatchCertificateResponseObject" } }, "examples": { "pkcs12": { "$ref": "#/components/examples/downloadBatchCertificatePKCS12List" }, "pem": { "$ref": "#/components/examples/downloadBatchCertificatePEMList" } } } } } } } }, "/v1/certificate-download/certificate-value/{certificate_value}?format=value": { "get": { "operationId": "downloadByCertificateValue", "summary": "Download certificate by certificate value. The format will default to PEM if non is specified.", "tags": [ "External batch certificate enrollment" ], "description": "Use this endpoint to download the certificate and private key for a certificate with the given certificate value. To use this operation, the certificate must have been issued using the `EXTERNAL_BATCH` enrollment method.\n\nThis endpoint returns multiple certificates if the certificate value is not unique. Responses with multiple certificates are sorted in descending order by the creation date and time of the certificate.\n", "parameters": [ { "in": "path", "name": "certificate_value", "description": "Certificate value for the certificate.", "required": true, "schema": { "example": "Certificate value", "type": "string" } }, { "in": "query", "name": "format", "description": "Certificate download format (`pem` or `pkcs12`).", "required": false, "schema": { "type": "string", "example": "pem", "enum": [ "pem", "pkcs12" ] } } ], "responses": { "200": { "description": "Downloaded certificates and private keys.", "content": { "application/json": { "schema": { "type": "array", "description": "List of objects with certificate data.", "items": { "$ref": "#/components/schemas/downloadBatchCertificateResponseObject" } }, "examples": { "pkcs12": { "$ref": "#/components/examples/downloadBatchCertificatePKCS12List" }, "pem": { "$ref": "#/components/examples/downloadBatchCertificatePEMList" } } } } } } } }, "/v1/certificate-download/job/{job_id}/certificate-value/{certificate_value}/format/{format}": { "get": { "operationId": "downloadByJobIdAndCertificateValue", "summary": "Download certificate by job ID and certificate value", "tags": [ "External batch certificate enrollment" ], "description": "Use this endpoint to download the certificate and private key for a certificate with the given job ID and certificate value. To use this operation, the certificate must have been issued using the `EXTERNAL_BATCH` enrollment method.\n\nThis endpoint returns multiple certificates if the certificate value is not unique. Responses with multiple certificates are sorted in descending order by the creation date and time of the certificate.\n", "parameters": [ { "$ref": "#/components/parameters/batch_job_id" }, { "in": "path", "name": "certificate_value", "description": "Certificate value for the certificate.", "required": true, "schema": { "example": "Certificate value", "type": "string" } }, { "in": "path", "name": "format", "description": "Certificate download format (`pem` or `pkcs12`).", "required": true, "schema": { "type": "string", "example": "pem", "enum": [ "pem", "pkcs12" ] } } ], "responses": { "200": { "description": "Downloaded certificates and private keys.", "content": { "application/json": { "schema": { "type": "array", "description": "List of objects with certificate data.", "items": { "$ref": "#/components/schemas/downloadBatchCertificateResponseObject" } }, "examples": { "pkcs12": { "$ref": "#/components/examples/downloadBatchCertificatePKCS12List" }, "pem": { "$ref": "#/components/examples/downloadBatchCertificatePEMList" } } } } } } } }, "/v1/device-profile": { "post": { "tags": [ "Device profiles" ], "summary": "Create device profile", "operationId": "createDeviceProfile", "description": "Use this endpoint to create a device profile.\n\nTo create a device profile, your request must include the ID of the division the device profile will be assigned to. You can get the ID for a division from the division details page in DigiCert® .\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Object with device profile information.", "required": [ "name", "division_id", "fields" ], "properties": { "name": { "type": "string", "description": "Device profile name. Character limit: 64\n", "example": "Example Device Profile" }, "division_id": { "type": "string", "description": "ID of the division the device profile is assigned to.\n", "example": "618b1e36-665e-475a-85cc-e2ebc73633b2" }, "description": { "type": "string", "example": "Custom description", "description": "Custom device profile description. Character limit: 1024\n" }, "fields": { "type": "array", "description": "List of objects defining custom fields for the device profile. To create a device profile without any custom fields, submit an empty array (`[]`). Limit: 40 fields\n", "items": { "type": "object", "description": "Object with information about a custom device field.", "properties": { "name": { "type": "string", "description": "Field name. Should be unique to this device profile. Character limit: 64\n", "example": "Optional custom field" }, "mandatory": { "type": "boolean", "description": "If true, the field is required when using this device profile to create a device. If false, the field is optional.\n", "example": false } } } }, "device_api_allow_read": { "type": "boolean", "description": "If true, devices using this profile can read their own device information by submitting a request to the `GET /v2/device/{device_id}` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.\n", "example": true }, "device_api_allow_renew_certificate": { "type": "boolean", "description": "If true, devices using this profile can renew their own certificates by submitting a request to the `PUT /v2/device/{device_id}/renew` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "example": true }, "device_api_allow_revoke": { "type": "boolean", "description": "If true, devices using this profile can revoke their own certificates by submitting a request to the `PUT /v2/device/{device_id}/revoke` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record." }, "device_api_allow_write": { "type": "boolean", "description": "If true, devices using this profile can update their own device information by submitting a request to the `PUT /v2/device/{device_id}` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record." } } } } } }, "responses": { "201": { "description": "Object with device profile information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceProfileResponse" } } } } } }, "get": { "tags": [ "Device profiles" ], "summary": "List device profiles", "description": "Use this endpoint to get a list of device profiles, or to search for profiles that meet the given criteria.\n", "parameters": [ { "in": "query", "name": "name", "description": "Limit results to device profiles with a name that contains the given string.", "schema": { "type": "string", "example": "Device profile name" } }, { "in": "query", "name": "status", "description": "Limit results to device profiles with the given status.", "schema": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "account_id", "description": "Limits results to device profiles for an account with the given ID.", "schema": { "type": "string", "format": "UUID", "example": "b29cc018-620e-4d4d-8488-c02e19e937b0" } }, { "in": "query", "name": "division_id", "description": "Limits results to device profiles for a division with the given ID.", "schema": { "type": "string", "example": "63c999ef-d4a0-4dd8-a7fc-e14ebe0167c5" } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20, "example": 1 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of objects with device profile information.", "content": { "application/json": { "schema": { "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of device profile records.", "items": { "$ref": "#/components/schemas/deviceProfileResponse" } } } }, "example": { "limit": 20, "offset": 0, "pagination": true, "next": false, "total": 2, "records": [ { "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_revoke": true, "device_api_allow_renew_certificate": true, "device_api_allow_enroll_certificate": false, "name": "Example device profile", "description": "Example description", "id": "7af1665a-312b-4623-bc42-4ecdc3a991e4", "status": "ACTIVE", "fields": [ { "id": "a23359cf-4d46-4a6f-8836-b57ade0ba490", "name": "mandatory", "mandatory": true }, { "id": "5cec6af9-03d4-42a2-8a6f-398e02f9ff06", "name": "optional", "mandatory": false } ], "division": { "id": "7916bac3-9e40-42bc-9ca1-9e6be33ed4f5", "name": "IoT Account" }, "account_id": "5765eaa2-4e4d-4505-8f43-4193aeef2137" }, { "device_api_allow_read": false, "device_api_allow_write": false, "device_api_allow_revoke": false, "device_api_allow_renew_certificate": false, "device_api_allow_enroll_certificate": false, "name": "Example device profile 2", "id": "14b5b58b-170a-4282-ad6a-f7323361a88e", "status": "ACTIVE", "fields": [], "division": { "id": "16ab78eb-09c3-449a-86a8-542c95edd310", "name": "External Account" }, "account_id": "5c84f89c-46d3-4554-a2d2-c3daa81b153f" } ] } } } } } } }, "/v1/device-profile/{device_profile_id}": { "get": { "tags": [ "Device profiles" ], "summary": "Get device profile", "operationId": "getDeviceProfile", "description": "Use this endpoint to get information about a device profile.\n", "parameters": [ { "in": "path", "name": "device_profile_id", "required": true, "description": "Device profile ID (UUID)", "schema": { "format": "uuid", "type": "string", "example": "dcfe811c-ecf1-4d2e-bf44-462963bc4ade" } } ], "responses": { "200": { "description": "Object with device profile information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceProfileResponse" } } } } } }, "put": { "tags": [ "Device profiles" ], "operationId": "updateDeviceProfile", "summary": "Update device profile", "description": "Use this endpoint to update the device profile with the given ID.\n", "parameters": [ { "in": "path", "name": "device_profile_id", "required": true, "description": "Device profile ID (UUID)", "schema": { "format": "uuid", "type": "string", "example": "dcfe811c-ecf1-4d2e-bf44-462963bc4ade" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Object with device profile information.", "required": [ "name", "division_id", "fields" ], "properties": { "name": { "type": "string", "description": "Device profile name. Character limit: 64\n", "example": "Example Device Profile" }, "division_id": { "type": "string", "description": "ID of the division the device profile is assigned to.\n", "example": "5c84f89c-46d3-4554-a2d2-c3daa81b153f" }, "description": { "type": "string", "example": "Custom description", "description": "Custom device profile description. Character limit: 1024\n" }, "fields": { "type": "array", "description": "List of objects defining custom fields for the device profile. To create a device profile without any custom fields, submit an empty array (`[]`). Limit: 40 fields\n", "items": { "type": "object", "description": "Object with information about a custom device field.", "properties": { "name": { "type": "string", "description": "Field name. Should be unique to this device profile. Character limit: 64\n", "example": "Optional custom field" }, "mandatory": { "type": "boolean", "description": "If true, the field is required when using this device profile to create a device. If false, the field is optional.\n", "example": false } } } }, "device_api_allow_read": { "type": "boolean", "description": "If true, devices using this profile can read their own device information by submitting a request to the `GET /v2/device/{device_id}` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.\n", "example": true }, "device_api_allow_renew_certificate": { "type": "boolean", "description": "If true, devices using this profile can renew their own certificates by submitting a request to the `PUT /v2/device/{device_id}/renew` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "example": true }, "device_api_allow_revoke": { "type": "boolean", "description": "If true, devices using this profile can revoke their own certificates by submitting a request to the `PUT /v2/device/{device_id}/revoke` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record." }, "device_api_allow_write": { "type": "boolean", "description": "If true, devices using this profile can update their own device information by submitting a request to the `PUT /v2/device/{device_id}` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record." } } } } } }, "responses": { "200": { "description": "Object with device profile details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceProfileResponse" } } } } } } }, "/v1/device-profile/{device_profile_id}/delete": { "put": { "tags": [ "Device profiles" ], "summary": "Delete device profile", "operationId": "deleteDeviceProfile", "description": "Use this endpoint to delete the device profile with the given ID. Deleted device profiles cannot be used in new enrollment profiles, but enrollment profiles that already use deleted device profiles will continue to issue certificates.\n", "parameters": [ { "in": "path", "name": "device_profile_id", "required": true, "description": "Device profile ID (UUID)", "schema": { "format": "uuid", "type": "string", "example": "dcfe811c-ecf1-4d2e-bf44-462963bc4ade" } } ], "responses": { "204": { "description": "Device profile deleted. No content." } } } }, "/v1/device-profile/{device_profile_id}/undelete": { "put": { "tags": [ "Device profiles" ], "summary": "Restore device profile", "operationId": "restoreDeviceProfile", "description": "Use this endpoint to restore a deleted device profile.\n", "parameters": [ { "in": "path", "name": "device_profile_id", "required": true, "description": "Device profile ID (UUID)", "schema": { "format": "uuid", "type": "string", "example": "dcfe811c-ecf1-4d2e-bf44-462963bc4ade" } } ], "responses": { "204": { "description": "Device profile restored. No content." } } } }, "/v1/device": { "post": { "tags": [ "Devices" ], "operationId": "createDevice", "summary": "Create device", "description": "Use this endpoint to add a device to manage. The request body includes the device profile that the new device configuration must follow. It also includes any fields the device profile requires.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDeviceRequest" } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing, a value is not valid, or a device with this name already exists.", "value": { "code": "invalid_input", "message": "Device with division {division_id} and identifier {device_identifier} already exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "get": { "tags": [ "Devices" ], "operationId": "getDeviceList", "summary": "Get device list", "description": "Use this endpoint to get a list of records with information about your devices.", "parameters": [ { "in": "query", "name": "device_identifier", "description": "Limits response data to records that use a specific device identifier.", "schema": { "type": "string", "maxLength": 255, "example": "Device name" } }, { "in": "query", "name": "created_from", "description": "Limits response data to device records created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits response data to device records created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "division_id", "description": "Limits response data to device records associated with a specific division ID.", "schema": { "$ref": "#/components/schemas/division_id" } }, { "in": "query", "name": "updated_from", "description": "Limits response data to device records updated after a specific date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "updated_to", "description": "Limits response data to device records updated before a specific date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "device_profile_id", "description": "Limits response data to device records with a specific device profile ID.", "schema": { "type": "string", "example": "a81a431a-be7b-4f2e-8afd-b2778491511f" } }, { "$ref": "#/components/parameters/pagination" }, { "in": "query", "name": "limit", "description": "Number of device records to include in the results.", "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "offset", "description": "Offset index of the first device record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of objects with device record details.", "items": { "oneOf": [ { "$ref": "#/components/schemas/deviceResponseObject" } ] } } }, "example": { "limit": 0, "offset": 0, "pagination": true, "next": false, "total": 1, "records": [ { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "f92834ce-cdea-1584-b154-193bb198345e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Division name" }, "device_identifier": "Device name", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device profile name" }, "created": "2020-12-16T22:09:53.035Z", "updated": "2020-12-16T22:09:53.035Z", "status": "ACTIVE", "fields": [ { "id": "123c456e-789c-1e23-4567-ee90f39458fb", "name": "Field name", "value": "Field value", "mandatory": true } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } ] } } } } } } } }, "/v1/device/{device_identifier}": { "get": { "tags": [ "Devices" ], "operationId": "getDeviceDetails", "summary": "Get device details", "description": "Use this endpoint to get device details, including status and attributes.", "parameters": [ { "$ref": "#/components/parameters/device_identifier" }, { "$ref": "#/components/parameters/division_id" } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with division {division_id} and identifier {device_identifier} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "put": { "tags": [ "Devices" ], "operationId": "updateDevice", "summary": "Update device", "description": "Updates field values for an existing device. Optionally, updates the device name (or `device_identifier`). Device ID cannot be changed.\n\n**Note:** This operation is destructive to the `fields` array. The field values in your request overwrite existing field values for the device. Omitting field values from the request causes existing values to be deleted.\n", "parameters": [ { "$ref": "#/components/parameters/device_identifier" }, { "$ref": "#/components/parameters/division_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateDeviceRequest" } } } }, "responses": { "200": { "description": "Device successfully updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with division {division_id} and identifier {device_identifier} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing, a value is not valid, or a device with this name already exists.", "value": { "code": "invalid_input", "message": "Device with division {division_id} and identifier {device_identifier} already exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "delete": { "tags": [ "Devices" ], "operationId": "archiveDevice", "summary": "Archive device", "description": "Use this endpoint to remove a device from certificate management and reporting when the device is no longer in service. The device record is not deleted entirely and can be restored.", "parameters": [ { "$ref": "#/components/parameters/device_identifier" }, { "$ref": "#/components/parameters/division_id" } ], "responses": { "200": { "description": "Device successfully archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" }, "example": { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Mock Division 1" }, "device_identifier": "New Device", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device Profile" }, "created": "2020-04-22T07:13:20Z", "updated": "2020-04-24T09:23:21Z", "status": "DELETED", "fields": [ { "id": "417c328e-604c-4e94-9112-ee58f12277fb", "name": "Mandatory Field", "value": "updated mandatory value", "mandatory": true }, { "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de", "name": "Optional Field", "value": "updated optional value", "mandatory": false } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with division {division_id} and identifier {device_identifier} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/device/{device_identifier}/enable": { "put": { "tags": [ "Devices" ], "operationId": "enableDevice", "summary": "Enable device", "description": "Use this endpoint to enable a disabled device.", "parameters": [ { "$ref": "#/components/parameters/device_identifier" }, { "$ref": "#/components/parameters/division_id" } ], "responses": { "200": { "description": "Device successfully enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" }, "example": { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Mock Division 1" }, "device_identifier": "New Device", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device Profile" }, "created": "2020-04-22T07:13:20Z", "updated": "2020-04-24T09:23:21Z", "status": "ACTIVE", "fields": [ { "id": "417c328e-604c-4e94-9112-ee58f12277fb", "name": "Mandatory Field", "value": "updated mandatory value", "mandatory": true }, { "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de", "name": "Optional Field", "value": "updated optional value", "mandatory": false } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with division {division_id} and identifier {device_identifier} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/device/{device_identifier}/disable": { "put": { "tags": [ "Devices" ], "operationId": "disableDevice", "summary": "Disable device", "description": "Use this endpoint to disable an enabled device.", "parameters": [ { "$ref": "#/components/parameters/device_identifier" }, { "$ref": "#/components/parameters/division_id" } ], "responses": { "200": { "description": "Device successfully disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" }, "example": { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Mock Division 1" }, "device_identifier": "New Device", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device Profile" }, "created": "2020-04-22T07:13:20Z", "updated": "2020-04-24T09:23:21Z", "status": "DISABLED", "fields": [ { "id": "417c328e-604c-4e94-9112-ee58f12277fb", "name": "Mandatory Field", "value": "updated mandatory value", "mandatory": true }, { "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de", "name": "Optional Field", "value": "updated optional value", "mandatory": false } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with division {division_id} and identifier {device_identifier} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/device/{device_identifier}/undelete": { "put": { "tags": [ "Devices" ], "operationId": "restoreDevice", "summary": "Restore device", "description": "Use this endpoint to restore an archived device.", "parameters": [ { "$ref": "#/components/parameters/device_identifier" }, { "$ref": "#/components/parameters/division_id" } ], "responses": { "200": { "description": "Device successfully restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" }, "example": { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Mock Division 1" }, "device_identifier": "New Device", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device Profile" }, "created": "2020-04-22T07:13:20Z", "updated": "2020-04-24T09:23:21Z", "status": "ACTIVE", "fields": [ { "id": "417c328e-604c-4e94-9112-ee58f12277fb", "name": "Mandatory Field", "value": "updated mandatory value", "mandatory": true }, { "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de", "name": "Optional Field", "value": "updated optional value", "mandatory": false } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with division {division_id} and identifier {device_identifier} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v2/device": { "post": { "tags": [ "Devices (v2)" ], "operationId": "createDevice_v2", "summary": "Create device by ID.", "description": "Use this endpoint to add a device to manage. The request body includes the device profile that the new device configuration must follow. It also includes any fields the device profile requires.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDeviceRequest" } } } }, "responses": { "200": { "description": "Device successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing, a value is not valid, or a device with this name already exists.", "value": { "code": "invalid_input", "message": "Device with division {division_id} and identifier {device_identifier} already exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "get": { "tags": [ "Devices (v2)" ], "operationId": "getDeviceList_v2", "summary": "Get device list", "description": "Use this endpoint to get a list of records with information about your devices.", "parameters": [ { "in": "query", "name": "device_identifier", "description": "Limits response data to records that use a specific device identifier.", "schema": { "type": "string", "maxLength": 255, "example": "Device name" } }, { "in": "query", "name": "created_from", "description": "Limits response data to device records created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits response data to device records created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "division_id", "description": "Limits response data to device records associated with a specific division ID.", "schema": { "$ref": "#/components/schemas/division_id" } }, { "in": "query", "name": "updated_from", "description": "Limits response data to device records updated after a specific date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "updated_to", "description": "Limits response data to device records updated before a specific date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "device_profile_id", "description": "Limits response data to device records with a specific device profile ID.", "schema": { "type": "string", "example": "a81a431a-be7b-4f2e-8afd-b2778491511f" } }, { "$ref": "#/components/parameters/pagination" }, { "in": "query", "name": "limit", "description": "Number of device records to include in the results.", "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "offset", "description": "Offset index of the first device record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of objects with device record details.", "items": { "oneOf": [ { "$ref": "#/components/schemas/deviceResponseObject" } ] } } }, "example": { "limit": 0, "offset": 0, "pagination": true, "next": false, "total": 1, "records": [ { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "f92834ce-cdea-1584-b154-193bb198345e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Division name" }, "device_identifier": "Device name", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device profile name" }, "created": "2020-12-16T22:09:53.035Z", "updated": "2020-12-16T22:09:53.035Z", "status": "ACTIVE", "fields": [ { "id": "123c456e-789c-1e23-4567-ee90f39458fb", "name": "Field name", "value": "Field value", "mandatory": true } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } ] } } } } } } } }, "/v2/device/{device_id}": { "get": { "tags": [ "Devices (v2)" ], "operationId": "getDeviceDetails_v2", "summary": "Get device details by ID (supports client certificate auth)", "description": "Use this endpoint to get device details, including status and attributes.\n\n**Using TLS authentication**\n\nThis endpoint supports mutual TLS authentication. This means a client can access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication instead of an API key, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nUse TLS authentication when:\n- You need to configure a device to read and update its own data.\n- You do not want to allow the device to read and write data for other devices or access endpoints that require an API key.\n\nTo access this endpoint with TLS authentication:\n\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_read` property for the device must be set to `true`. To change the value of this property, use the `PUT /v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® IoT Trust Manager console.\n", "parameters": [ { "$ref": "#/components/parameters/device_id" } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with id {device_id} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "put": { "tags": [ "Devices (v2)" ], "operationId": "updateDevice_v2", "summary": "Update device by ID (supports client certificate auth)", "description": "Updates field values for an existing device. Optionally, updates the device name (or `device_identifier`). Device ID cannot be changed.\n\n**Note:** This operation is destructive to the `fields` array. The field values in your request overwrite existing field values for the device. Omitting field values from the request causes existing values to be deleted.\n\n**Using TLS authentication**\n\nThis endpoint supports mutual TLS authentication. This means a client can access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication instead of an API key, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nUse TLS authentication when:\n- You need to configure a device to read and update its own data.\n- You do not want to allow the device to read and write data for other devices or access endpoints that require an API key.\n\nTo access this endpoint with TLS authentication:\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_update` property for the device must be set to `true`. To change the value of this property, use the `PUT /v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® IoT Trust Manager console.\n", "parameters": [ { "$ref": "#/components/parameters/device_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateDeviceRequest" } } } }, "responses": { "200": { "description": "Device successfully updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with id {device_id} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing, a value is not valid, or a device with this name already exists.", "value": { "code": "invalid_input", "message": "Device with division {division_id} and identifier {device_identifier} already exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "delete": { "tags": [ "Devices (v2)" ], "operationId": "archiveDevice_v2", "summary": "Archive device by ID", "description": "Use this endpoint to remove a device from certificate management and reporting when the device is no longer in service. The device record is not deleted entirely and can be restored.", "parameters": [ { "$ref": "#/components/parameters/device_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" }, "example": { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Mock Division 1" }, "device_identifier": "New Device", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device Profile" }, "created": "2020-04-22T07:13:20Z", "updated": "2020-04-24T09:23:21Z", "status": "DELETED", "fields": [ { "id": "417c328e-604c-4e94-9112-ee58f12277fb", "name": "Mandatory Field", "value": "updated mandatory value", "mandatory": true }, { "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de", "name": "Optional Field", "value": "updated optional value", "mandatory": false } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with id {device_id} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v2/device/{device_id}/enable": { "put": { "tags": [ "Devices (v2)" ], "operationId": "enableDevice_v2", "summary": "Enable device by ID", "description": "Use this endpoint to enable a disabled device.", "parameters": [ { "$ref": "#/components/parameters/device_id" } ], "responses": { "200": { "description": "Device successfully enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" }, "example": { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Mock Division 1" }, "device_identifier": "New Device", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device Profile" }, "created": "2020-04-22T07:13:20Z", "updated": "2020-04-24T09:23:21Z", "status": "ACTIVE", "fields": [ { "id": "417c328e-604c-4e94-9112-ee58f12277fb", "name": "Mandatory Field", "value": "updated mandatory value", "mandatory": true }, { "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de", "name": "Optional Field", "value": "updated optional value", "mandatory": false } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with id {device_id} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v2/device/{device_id}/disable": { "put": { "tags": [ "Devices (v2)" ], "operationId": "disableDevice_v2", "summary": "Disable device by ID", "description": "Use this endpoint to disable an enabled device.", "parameters": [ { "$ref": "#/components/parameters/device_id" } ], "responses": { "200": { "description": "Device successfully disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" }, "example": { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Mock Division 1" }, "device_identifier": "New Device", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device Profile" }, "created": "2020-04-22T07:13:20Z", "updated": "2020-04-24T09:23:21Z", "status": "DISABLED", "fields": [ { "id": "417c328e-604c-4e94-9112-ee58f12277fb", "name": "Mandatory Field", "value": "updated mandatory value", "mandatory": true }, { "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de", "name": "Optional Field", "value": "updated optional value", "mandatory": false } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with id {device_id} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v2/device/{device_id}/undelete": { "put": { "tags": [ "Devices (v2)" ], "operationId": "restoreDevice_v2", "summary": "Restore device by ID", "description": "Use this endpoint to restore an archived device.", "parameters": [ { "$ref": "#/components/parameters/device_id" } ], "responses": { "200": { "description": "Device successfully restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" }, "example": { "id": "64c02969-3890-4da8-a5ef-b574fd72887e", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "division": { "id": "fd5faa1e-623a-47a9-831b-b9397c33395f", "name": "Mock Division 1" }, "device_identifier": "New Device", "device_profile": { "id": "a81a431a-be7b-4f2e-8afd-b2778491511f", "name": "Device Profile" }, "created": "2020-04-22T07:13:20Z", "updated": "2020-04-24T09:23:21Z", "status": "ACTIVE", "fields": [ { "id": "417c328e-604c-4e94-9112-ee58f12277fb", "name": "Mandatory Field", "value": "updated mandatory value", "mandatory": true }, { "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de", "name": "Optional Field", "value": "updated optional value", "mandatory": false } ], "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_renew_certificate": true } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with id {device_id} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v2/device/{device_id}/renew": { "post": { "tags": [ "Devices (v2)" ], "operationId": "renewDeviceCertificate_v2", "summary": "Renew device certificate by device ID (client certificate auth only)", "description": "Use this endpoint to renew an existing certificate for a device.\n\n**Using TLS authentication**\n\nYou can only access this endpoint by using mutual TLS authentication. Mutual TLS authentication allows a client to access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nTo access this endpoint with TLS authentication:\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_renew_certificate` property for the device must be set to `true`. To change the value of this property, use the **PUT** `/v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® console.\n", "parameters": [ { "$ref": "#/components/parameters/device_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/renewCertificateRequest" } } } }, "responses": { "200": { "description": "Successful renewal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with id {invalid} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid authentication certificate.", "value": { "code": "access_denied", "message": "No client certificate to authenticate" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v2/device/{device_id}/revoke": { "post": { "tags": [ "Devices (v2)" ], "operationId": "revokeDeviceCertificate_v2", "summary": "Revoke device certificate by device ID (client certificate auth only)", "description": "Use this endpoint to revoke an existing certificate for a device. Provide `certificate_id` or `certificate_serial_number` or `certificate_thumbprint` to identify certificate to revoke.\n\n**Using TLS authentication**\n\nYou can only access this endpoint by using mutual TLS authentication. Mutual TLS authentication allows a client to access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nTo access this endpoint with TLS authentication:\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_revoke` property for the device must be set to `true`. To change the value of this property, use the **PUT** `/v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® console.\n", "parameters": [ { "$ref": "#/components/parameters/device_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/revokeDeviceCertificateRequest" } } } }, "responses": { "204": { "description": "No content." }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device with id {invalid} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid authentication certificate.", "value": { "code": "access_denied", "message": "No client certificate to authenticate" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v3/device/{device_identifier}": { "get": { "tags": [ "Devices (v3)" ], "operationId": "getDeviceDetails_v3", "summary": "Get device details by device_identifier (supports only client certificate auth)", "description": "Use this endpoint to get device details, including status and attributes.\n\n**Using TLS authentication**\n\nThis endpoint supports mutual TLS authentication. This means a client can access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication instead of an API key, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nUse TLS authentication when:\n- You need to configure a device to read and update its own data.\n- You do not want to allow the device to read and write data for other devices or access endpoints that require an API key.\n\nTo access this endpoint with TLS authentication:\n\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_read` property for the device must be set to `true`. To change the value of this property, use the `PUT /v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® IoT Trust Manager console.\n", "parameters": [ { "$ref": "#/components/parameters/device_identifier" } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device not found" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to invalid authentication certificate or flag device_api_allow_read is not set to true.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "put": { "tags": [ "Devices (v3)" ], "operationId": "updateDevice_v3", "summary": "Update device by device_identifier (supports client certificate auth)", "description": "Updates field values for an existing device. Optionally, updates the device name (or `device_identifier`). Device ID cannot be changed.\n\n**Note:** This operation is destructive to the `fields` array. The field values in your request overwrite existing field values for the device. Omitting field values from the request causes existing values to be deleted.\n\n**Using TLS authentication**\n\nThis endpoint supports mutual TLS authentication. This means a client can access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication instead of an API key, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nUse TLS authentication when:\n- You need to configure a device to read and update its own data.\n- You do not want to allow the device to read and write data for other devices or access endpoints that require an API key.\n\nTo access this endpoint with TLS authentication:\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_update` property for the device must be set to `true`. To change the value of this property, use the `PUT /v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® IoT Trust Manager console.\n", "parameters": [ { "$ref": "#/components/parameters/device_identifier" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateDeviceRequest" } } } }, "responses": { "200": { "description": "Device successfully updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device not found" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing, a value is not valid, or a device with this name already exists.", "value": { "code": "invalid_input", "message": "Device with division {division_id} and identifier {device_identifier} already exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_DEVICE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v3/device/{device_identifier}/renew": { "post": { "tags": [ "Devices (v3)" ], "operationId": "renewDeviceCertificate_v3", "summary": "Renew device certificate by device_identifier (client certificate auth only)", "description": "Use this endpoint to renew an existing certificate for a device. Provide `certificate_id` or `certificate_serial_number`, `certificate_thumbprint` or `certificate_body` to identify certificate to renew.\n\n**Using TLS authentication**\n\nYou can only access this endpoint by using mutual TLS authentication. Mutual TLS authentication allows a client to access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nTo access this endpoint with TLS authentication:\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_renew_certificate` property for the device must be set to `true`. To change the value of this property, use the **PUT** `/v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® console.\n", "parameters": [ { "$ref": "#/components/parameters/device_identifier" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/renewDeviceCertificateRequest" } } } }, "responses": { "200": { "description": "Successful renewal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device not found" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid authentication certificate.", "value": { "code": "access_denied", "message": "No client certificate to authenticate" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v3/device/{device_identifier}/revoke": { "post": { "tags": [ "Devices (v3)" ], "operationId": "revokeDeviceCertificate_v3", "summary": "Revoke device certificate by device ID (client certificate auth only)", "description": "Use this endpoint to revoke an existing certificate for a device. Provide `certificate_id` or `certificate_serial_number`, `certificate_thumbprint` or `certificate_body` to identify certificate to revoke.\n\n**Using TLS authentication**\n\nYou can only access this endpoint by using mutual TLS authentication. Mutual TLS authentication allows a client to access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nTo access this endpoint with TLS authentication:\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_revoke` property for the device must be set to `true`. To change the value of this property, use the **PUT** `/v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® console.\n", "parameters": [ { "$ref": "#/components/parameters/device_identifier" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/revokeDeviceCertificateRequest" } } } }, "responses": { "204": { "description": "No content." }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device not found" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid authentication certificate.", "value": { "code": "access_denied", "message": "No client certificate to authenticate" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v3/device/{device_identifier}/certificate": { "get": { "tags": [ "Devices (v3)" ], "operationId": "getCertificateDetails_v3", "summary": "Get certificate details assigned to a device (supports only client certificate auth)", "description": "Use this endpoint to get certificate details. Provide `certificate_id` or `certificate_serial_number`, `certificate_thumbprint` or `certificate_body` to identify certificate.\n\n**Using TLS authentication**\n\nThis endpoint supports mutual TLS authentication. This means a client can access the endpoint by presenting a trusted certificate in the request instead of using an API key.\n\nTo use TLS authentication instead of an API key, you must prefix the server hostname in the base URL with `clientauth`. For example, instead of `https://one.digicert.com`, use `https://clientauth.one.digicert.com`.\n\nUse TLS authentication when:\n- You need to configure a device to read and update its own data.\n- You do not want to allow the device to read and write data for other devices or access endpoints that require an API key.\n\nTo access this endpoint with TLS authentication:\n\n- The certificate in the API request must be a certificate that is associated with the device.\n- The `device_api_allow_read` property for the device must be set to `true`. To change the value of this property, use the `PUT /v2/device/{device_id}` endpoint. Alternatively, edit the settings for the device from the DigiCert® IoT Trust Manager console.\n", "parameters": [ { "$ref": "#/components/parameters/device_identifier" }, { "in": "query", "name": "id", "description": "Certificate ID to fetch.", "schema": { "type": "string", "example": "66666666-7777-8888-9999-000000000000" } }, { "in": "query", "name": "serial_number", "description": "Serial number of the certificate to fetch.", "schema": { "type": "string", "example": "4AEB02DBF882D9BEA9DB5E5D9F1E5E939B6B74D4" } }, { "in": "query", "name": "thumbprint", "description": "SHA256 thumbprint of the certificate to fetch.", "schema": { "type": "string", "example": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143" } }, { "in": "query", "name": "body", "description": "PEM formatted certificate body.", "schema": { "type": "string", "maxLength": 255, "example": "-----BEGIN CERTIFICATE-----\nMIICrjCCAZagAwIBAgIUIm...\n-----END CERTIFICATE-----" } } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceCertificateResponseObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Device not found" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to invalid authentication certificate or flag device_api_allow_read is not set to true.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/enrollment-profile": { "get": { "tags": [ "Enrollment profiles" ], "summary": "List enrollment profiles", "operationId": "listEnrollmentProfiles", "description": "Use this endpoint to get a list of records with information about the enrollment profiles in your DigiCert® IoT Trust Manager account.\n", "parameters": [ { "in": "query", "name": "name", "description": "Limits results to enrollment profiles with a name that contains the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "enrollment_profile_name" } }, { "in": "query", "name": "device_profile_id", "description": "Limits results to enrollment profiles with a device profile ID that is an exact match for the given string. Case-insensitive.\n", "schema": { "$ref": "#/components/schemas/device_profile_id" } }, { "in": "query", "name": "device_profile_name", "description": "Limits results to enrollment profiles with a device profile name that starts with the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "device_profile_name" } }, { "in": "query", "name": "enrollment_methods", "description": "Limits results to enrollment profiles that use any of the enrollment methods from the given comma-separated list. Case-insensitive.\n", "schema": { "type": "string", "example": "API,PORTAL", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH" ] } }, { "in": "query", "name": "ip_addresses", "description": "Limits results to enrollment profiles that allow requests from all IP addresses in the given comma-separated list.\n", "schema": { "type": "string", "example": "192.0.2.0,192.0.2.1" } }, { "in": "query", "name": "created_from", "description": "Limits results to enrollment profiles created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to enrollment profiles created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "certificate_type", "description": "Limits results to enrollment profiles for the given certificate type (end-entity or intermediate). Case-insensitive.\n", "schema": { "type": "string", "enum": [ "END_ENTITY", "INTERMEDIATE" ], "example": "end-entity" } }, { "in": "query", "name": "status", "description": "Limits results to enrollment profiles with the given status. Case-insensitive.\n", "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "DELETED", "ALL" ] } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "type": "string", "enum": [ "id", "name", "device_profile_name", "enrollment_methods", "allowed_ip_addresses", "status", "expires_on" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 1000, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of enrollment profiles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of enrollment profile records.", "items": { "oneOf": [ { "$ref": "#/components/schemas/enrollmentProfileInList" } ] } } }, "example": { "limit": 20, "offset": 0, "pagination": true, "next": false, "total": 2, "records": [ { "name": "example 1", "enrollment_methods": [ "API", "PORTAL" ], "allowed_ip_addresses": [], "key_generation_allow_to_change": false, "key_generation_option": "client_side", "allow_key_cache": false, "require_approval_for_enroll": false, "require_approval_for_renew": false, "notification_email_list": [], "id": "IOT_9a71bed6-070c-4279-a907-6932fa9283e8", "device_profile": { "id": "eb4ef93d-03f2-4636-8fa5-a95203a926a6", "name": "Monitoring Devices" }, "certificate_profile": { "id": "71156da4-be18-427c-b930-c8c7f8652ed8", "name": "example 1" }, "created_at": "2022-04-01T06:27:36Z", "ica": { "id": "49A22367623B6C98F1F023D3311CEE53", "name": "example ica 1" }, "status": "ACTIVE", "allowed_signature_algorithms": [ "sha512WithRSA", "sha256WithRSA", "sha384WithRSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA" ], "direct_mapping": true, "account_id": "e7eee849-cee5-419e-8327-896a895ba182", "certificate_type": "end_entity", "ca_body": "", "ca_chain": [ { "cert_type": "intermediate", "blob": "", "common_name": "example ica 1" }, { "cert_type": "root", "blob": "", "common_name": "example rsa root" } ], "certificate_template": { "id": "2d2ef265-6a55-4099-ade3-2e09980abf72", "name": "example 1" } }, { "name": "example 2", "enrollment_methods": [ "API", "PORTAL" ], "allowed_ip_addresses": [], "key_generation_allow_to_change": false, "allow_key_cache": false, "require_approval_for_enroll": false, "require_approval_for_renew": false, "notification_email_list": [], "id": "IOT_3945d528-2e88-45cd-8237-41ece6e05bb4", "device_profile": { "id": "abb3da4a-c468-49d1-97b6-38a137a52bdd", "name": "Monitoring Devices" }, "certificate_profile": { "id": "bfc62380-8e6d-42e7-9d9f-a3f705127566", "name": "gp example" }, "created_at": "2022-03-30T07:01:07Z", "ica": { "id": "B9DD236F8A2BBA2B9FA3F1CCCF087AE9", "name": "example ica 2" }, "status": "ACTIVE", "allowed_signature_algorithms": [ "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA" ], "direct_mapping": true, "account_id": "e7eee849-cee5-419e-8327-896a895ba182", "certificate_type": "end_entity", "ca_body": "", "gp_ca_body": "", "ca_chain": [ { "cert_type": "intermediate", "blob": "", "common_name": "example ica 2" }, { "cert_type": "root", "blob": "", "common_name": "example root ca 2" } ], "gp_ca_chain": [ { "cert_type": "intermediate", "blob": "", "common_name": "example ica 2" }, { "cert_type": "root", "blob": "", "common_name": "example root ca 2" } ], "certificate_template": { "id": "a3e7e32c-64a1-4bbc-b7d6-f0396a569a03", "name": "gp template" }, "scep_get_ca_cert_response_with_root": false, "scep_get_ca_cert_response_der_format": false, "scep_encryption_algorithm": "aes128WithCBC" } ] } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "Please provide valid created from. Expected formats: YYYY-MM-DD or YYYY-MM-DDTHH-MM-SSZ" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } }, "post": { "tags": [ "Enrollment profiles" ], "summary": "Create enrollment profile", "operationId": "createEnrollmentProfile", "description": "Use this endpoint to create an enrollment profile.\n\nTo create an enrollment profile, your request must include the following key pieces of information.\n\n- From **DigiCert® IoT Trust Manager**, you need:\n - The ID of the certificate profile the enrollment profile will use.\n - The ID of the device profile the enrollment profile will use.\n- From **DigiCert® CA Manager**, you need:\n - The ID of the ICA that will issue certificates requested using the enrollment profile.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "enrollment_profile" ], "properties": { "enrollment_profile": { "type": "object", "description": "Object with enrollment profile details.\n\nWhen you send a request to create an enrollment profile, these parameters are required:\n\n- `name`\n- `enrollment_methods`\n- `device_profile_id`\n- `certificate_profile_id`\n- `ica_id`\n\nThese parameters are optional. Include them if you need to enforce usage restrictions or configure server-side keypair generation for the enrollment profile.\n\n- `allowed_ip_addresses`: Limits which IP addresses can use this enrollment profile to request certificates.\n- `allowed_hours_from`, `allowed_hours_to`, `timezone`: Defines a daily schedule when this enrollment profile can be used to request certificates.\n- `valid_from`, `valid_to`: Limits the period of time when this enrollment profile can be used to request certificates.\n- `key_generation_allow_to_change`, `key_generation_option`, `key_generation_type`: Configure keypair generation options for certificate requests and batch enrollment jobs that use the enrollment profile.\n", "required": [ "name", "enrollment_methods", "device_profile_id", "certificate_profile_id", "ica_id" ], "properties": { "name": { "type": "string", "description": "Enrollment profile name. Character limit: 64\n", "example": "Example name" }, "enrollment_methods": { "type": "array", "description": "List of enrollment methods enabled for the profile. Only `API`, `PORTAL`, and `BATCH` can be grouped together. If the enrollment profile uses a method other than `API`, `PORTAL`, or `BATCH`, the `enrollment_methods` array contains only one method.\n", "items": { "type": "string", "description": "Enrollment method.", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH", "EXTERNAL_BATCH" ] }, "example": [ "API", "PORTAL" ] }, "connector_url": { "type": "string", "description": "If `enrollment_method` is `EXTERNAL_BATCH`, base domain for DigiCert ONE instance where external enrollment profile exists. For example, `https://one.digicert.com`. Required if `enrollment_method` is `EXTERNAL_BATCH`. Otherwise, ignored.", "example": "https://one.digicert.com" }, "connector_type": { "type": "string", "description": "If `enrollment_method` is `EXTERNAL_BATCH`, method by which to authenticate to the external enrollment profile. Required if `enrollment_method` is `EXTERNAL_BATCH`. Otherwise, ignored. Possible values: `passcode`, `certificate`, `api_token`.\n", "enum": [ "passcode", "certificate", "api_token" ] }, "passcode": { "type": "string", "description": "If `enrollment_method` is `EXTERNAL_BATCH`, passcode for authenticating to external enrollment profile. Required if `connector_type` is `passcode`. Otherwise, ignored.\n", "example": "passcode" }, "api_key": { "type": "string", "description": "If `enrollment_method` is `EXTERNAL_BATCH`, API token for authenticating to external enrollment profile. The token must belong to an admin or service user in the DigiCert ONE instance where the external enrollment profile resides. Required if `connector_type` is `api_token`. Otherwise, ignored.\n", "example": "" }, "auth_cert_pkcs12": { "type": "string", "description": "If `enrollment_method` is `EXTERNAL_BATCH`, base 64-encoded string containing authentication certificate data for authenticating to external enrollment profile. Required if `connector_type` is `certificate`. Otherwise, ignored.\n", "example": "" }, "auth_cert_password_pkcs12": { "type": "string", "description": "If `enrollment_method` is `EXTERNAL_BATCH`, passcode for authentication certificate (`auth_cert_pkcs12`). Required if `connector_type` is `certificate`. Otherwise, ignored.", "example": "passcode" }, "external_enrollment_profile_id": { "type": "string", "description": "If `enrollment_method` is `EXTERNAL_BATCH`, ID of external enrollment profile. Required if `enrollment_method` is `EXTERNAL_BATCH`. Otherwise, ignored." }, "device_profile_id": { "type": "string", "description": "ID of the device profile this enrollment profile uses for certificate requests.", "example": "a8cb6d35-acb0-4274-b555-14c6730b0ba9" }, "certificate_profile_id": { "type": "string", "description": "ID of the certificate profile this enrollment profile uses for certificate requests.\n\nIf `enrollment_method` is `EXTERNAL_BATCH`, omit this field. Certificates will be issued using the certificate profile associated with the external enrollment profile.\n", "example": "cb8c59c1-5eb3-41d0-8664-d0343a09b3e7" }, "ica_id": { "type": "string", "description": "ID of the ICA that issues certificates requested through the enrollment profile.\n\n**Note:** If `enrollment_method` is `EXTERNAL_BATCH`, omit this field. Certificates will be issued using the ICA associated with the external enrollment profile.\n", "example": "AAC2E2DD6BEAE2E5EE93954BAE15E34D" }, "allowed_ip_addresses": { "type": "array", "description": "List of IP addresses allowed to request certificates using the enrollment profile. Support wildcards and ranges. If the enrollment profile will not validate IP addresses, omit the `allowed_ip_addresses` field from your request.\n", "items": { "type": "string", "example": "1.1.1.1, 192.160-170.*.1-100" } }, "allowed_hours_from": { "type": "string", "description": "Daily start time in the specified `timezone` (UTC if no `timezone` is set) for when certificates can be requested through the enrollment profile. Format: `HH:MM:SS`\n", "format": "date", "example": "09:45:00" }, "allowed_hours_to": { "type": "string", "description": "Daily end time in the specified `timezone` (UTC if no `timezone` is set) for when certificates can be requested through the enrollment profile. Format: `HH:MM:SS`\n", "format": "date", "example": "17:30:00" }, "timezone": { "type": "string", "description": "Region-based time zone ID for the `allowed_hours_from` and `allowed_hours_to` values. Format: `Area/Location` (for example, `America/New_York`). Accepts region names based on the Time Zone Database (tz database). See [list of tz database timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).\n", "example": "America/New_York" }, "valid_from": { "type": "string", "description": "Date the enrollment profile is valid from. Format: `YYYY-MM-DD`.\n", "example": "2021-06-25", "format": "date" }, "expires_on": { "type": "string", "description": "Date the enrollment profile expires. Format: `YYYY-MM-DD`.\n", "example": "2022-06-25", "format": "date" }, "key_generation_allow_to_change": { "type": "boolean", "description": "For certificate requests and batch enrollment jobs that use server-side keypair generation. If true, enrollment profile allows server-side keypair generation using any key type allowed in the certificate profile. You set the key type (`key_type`) when you request a certificate or submit a batch enrollment job. If false, the key type in certificate requests is ignored, and the enrollment profile's default key type (`key_generation_type`) is used.\n", "example": true, "default": false }, "key_generation_option": { "type": "string", "description": "Keypair generation option for certificate requests and batch enrollment jobs that use the enrollment profile. Case-insensitive.\n\nAllowed values:\n\n- `client_side` (default): Enrollment profile only allows client-side keypair generation.\n- `server_side`: Enrollment profile only allows server-side keypair generation.\n- `client_or_server_side`: Enrollment profile allows both client-side and server-side keypair generation.\n", "enum": [ "client_side", "server_side", "client_or_server_side" ], "example": "client_or_server_side", "default": "client_side" }, "key_generation_type": { "type": "string", "description": "Default key type for server-side keypair generation. Required if `key_generation_option` is `server_side` or `client_or_server_side`.\n", "example": "RSA_2048", "enum": [ "RSA_2048", "RSA_3072", "RSA_4096", "P_256", "P_384", "P_512", "ED_25519" ] }, "allow_key_cache": { "type": "boolean", "default": false, "description": "If true, when you request a certificate using server-side keypair generation, DigiCert IoT® Trust Manager caches the AES key that encrypts the returned keypair. Then, for a duration of your choosing (`key_cache_validity_period`), the same key encrypts keypairs returned by subsequent certificate requests. When this encryption key expires, the system generates a new one, which is cached for reuse in the same way.\n\nIf false (default), DigiCert IoT® Trust Manager generates a unique AES encryption key for each certificate request.\n\n**Note:** When `allow_key_cache` is true, `key_cache_validity_period_type` and `key_cache_validity_period` are required.\n" }, "key_cache_validity_period_type": { "type": "string", "description": "Unit of time for the key cache validity period. Required when `allow_key_cache` is true.\n", "example": "days", "enum": [ "days", "hours", "minutes", "seconds" ] }, "key_cache_validity_period": { "type": "string", "description": "Key cache validity period. Define unit of time measurement with `key_cache_validity_period_type`. Required when `allow_key_cache` is true.\n", "example": 1 }, "require_approval_for_enroll": { "type": "boolean", "default": false, "description": "If true, a user with `APPROVE_IOT_CERTIFICATE` permissions must approve enrollment requests created with this enrollment profile. Otherwise, false (default).\n\nEnrollment requests pending approval appear in the list of requests in your account. DigiCert® IoT Trust Manager only issues the certificate when the request is approved.\n\nTo require approvals, the enrollment profile must use an enrollment method of `API` or `PORTAL`.\n", "example": false }, "require_approval_for_renew": { "type": "boolean", "default": false, "description": "If true, a user with `APPROVE_IOT_CERTIFICATE` permissions must approve renewal requests created with this enrollment profile. Otherwise, false (default).\n\nRenewal requests pending approval appear in the list of requests in your account. DigiCert® IoT Trust Manager only issues the certificate when the request is approved.\n\nTo require approvals, the enrollment profile must use an enrollment method of `API` or `PORTAL`.\n", "example": false }, "digest_email_notification_period": { "type": "string", "description": "Frequency of request notification emails for the enrollment profile.\n\nAllowed values:\n* `individual_request`: DigiCert® IoT Trust Manager sends an email each time a request is created.\n\n* `daily_digest`: DigiCert® IoT Trust Manager sends a daily email with the total number of pending requests.\n\n* `do_not_send`: DigiCert® IoT Trust Manager doesn't send request notification emails.\n", "enum": [ "individual_request", "daily_digest", "do_not_send" ] }, "approvers": { "type": "array", "description": "List of IDs for users that receive request notification emails for the enrollment profile. If empty, all users with `APPROVE_IOT_CERTIFICATE` permissions receive request notification emails.\n", "items": { "type": "string", "format": "uuid", "description": "User ID.", "example": "1cc6f662-f93c-4a7e-a8e3-2829c8cf05be" } }, "notification_email_list": { "type": "array", "description": "List of additional email addresses that receive request notifications.\n", "items": { "type": "string", "description": "Email address.", "example": "example.com" } }, "scep_get_ca_cert_response_with_root": { "type": "boolean", "description": "Option to include root CA to GetCACert operation response. Only available for SCEP enrollment method.\n" }, "scep_get_ca_cert_response_der_format": { "type": "boolean", "description": "When set to true we force GetCACert operation response content type header to application/x-x509-ca-cert. Only available for SCEP enrollment method.\n" }, "scep_encryption_algorithm": { "type": "string", "description": "Encryption algorithm to use for response encryption. Default aes128WithCBC.\n", "enum": [ "aes128WithCBC", "aes256WithCBC", "desEDEWith3CBC" ] } } }, "mappings": { "type": "array", "description": "List of objects that describe how information from a certificate request is mapped to device fields when you request a certificate using this enrollment profile.", "items": { "type": "object", "properties": { "destination_id": { "type": "string", "description": "Mapping destination ID. Should be the ID of a device field.\n\n- To map to a device identifier, use `DEVICE_IDENTIFIER`.\n- To map to a custom device field, use the ID of the custom field. To view and copy custom field IDs, go to the device profile information page in DigiCert® IoT Trust Manager.\n", "example": "DEVICE_IDENTIFIER" }, "destination_type": { "type": "string", "description": "Mapping destination type. Must be `DEVICE`.", "example": "DEVICE", "enum": [ "DEVICE" ] }, "source_id": { "type": "string", "description": "Mapping source ID.\n\nIf the source type is `SYSTEM`, use one of the following:\n\n- `IP_ADDRESS`: Use the IP address of the user who requests the certificate.\n- `ENROLLMENT_METHOD`: Use the enrollment method for the certificate request.\n- `CURRENT_TIME`: Use the time the certificate request is created.\n\nIf the source type is `CERTIFICATE`, use the ID of the certificate attribute (for example, `subject.common_name`).\n", "example": "subject.common_name" }, "source_type": { "type": "string", "description": "Mapping source type. Can be either `CERTIFICATE` (a certificate attribute is the source of this information) or `SYSTEM` (DigiCert® IoT Trust Manager generates this information).\n", "enum": [ "CERTIFICATE", "SYSTEM" ] } } } } } }, "example": { "enrollment_profile": { "name": "Example enrollment profile", "device_profile_id": "7e873179-aab6-4acb-bfea-7dda35513926", "enrollment_methods": [ "API" ], "key_generation_option": "client_or_server_side", "key_generation_type": "RSA_2048", "key_generation_allow_to_change": true, "certificate_profile_id": "803b8a1c-065e-4a11-95e4-40b19b76eab9", "ica_id": "AAC2E2DD6BEAE2E5EE93954BAE15E34D" } } } } }, "responses": { "201": { "description": "Object with enrollment profile information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollment_profile": { "description": "Object with enrollment profile details.", "$ref": "#/components/schemas/enrollmentProfileResponse" }, "enrollment_profile_mappings": { "description": "Object with details about how the enrollment profile maps information to device fields.", "type": "object", "properties": { "mappings": { "type": "array", "description": "List of objects with information about each mapping source and destination.", "items": { "type": "object", "description": "Object with mapping details.", "properties": { "source_id": { "type": "string", "description": "Mapping source ID.\n\nIf the source type is `SYSTEM`, returns one of the following:\n\n- `IP_ADDRESS`: Use the IP address of the user who requests the certificate.\n- `ENROLLMENT_METHOD`: Use the enrollment method for the certificate request.\n- `CURRENT_TIME`: Use the time the certificate request is created.\n\nIf the source type is `CERTIFICATE`, contains the ID of the certificate attribute (for example, `subject.common_name`).\n", "example": "subject.common_name" }, "source_type": { "type": "string", "description": "Mapping source type. Can be either `CERTIFICATE` (a certificate attribute is the source of this information) or `SYSTEM` (DigiCert ONE generates this information).\n", "example": "CERTIFICATE", "enum": [ "CERTIFICATE", "SYSTEM" ] }, "source_name": { "type": "string", "description": "Source name.", "example": "subject.common_name" }, "destination_id": { "type": "string", "description": "ID of a device field the information is mapped to.", "example": "DEVICE_IDENTIFIER" }, "destination_type": { "type": "string", "description": "Destination type.", "enum": [ "DEVICE" ], "example": "DEVICE" }, "destination_mandatory": { "type": "boolean", "description": "If true, the destination is a required field. Otherwise, false.", "example": false } } } } } } } }, "example": { "enrollment_profile": { "name": "Example enrollment profile", "enrollment_methods": [ "API" ], "allowed_ip_addresses": [], "key_generation_type": "rsa_2048", "key_generation_allow_to_change": true, "key_generation_option": "client_or_server_side", "allow_key_cache": false, "require_approval_for_enroll": true, "require_approval_for_renew": true, "notification_email_list": [ "additional@example.com" ], "digest_email_notification_period": "individual_request", "approvers": [ { "id": "ae29ea9a-503e-40d7-91ed-07f57bb39320", "full_name": "John Doe", "email": "john.doe@example.com", "active": true, "user_type": "standard", "locale": "en_US" } ], "id": "IOT_9c007452-2942-44a5-9733-0b46cb20cb8d", "device_profile": { "id": "7e873179-aab6-4acb-bfea-7dda35513926", "name": "Device profile" }, "certificate_profile": { "id": "803b8a1c-065e-4a11-95e4-40b19b76eab9", "name": "Certificate profile" }, "created_at": "2022-05-28T06:45:49Z", "ica": { "id": "AAC2E2DD6BEAE2E5EE93954BAE15E34D", "name": "Example ICA" }, "status": "ACTIVE", "allowed_signature_algorithms": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA", "sha256WithRSAPSS", "sha384WithRSAPSS", "sha512WithRSAPSS" ], "direct_mapping": true, "account_id": "f92834ce-cdea-1584-b154-193bb198345e", "certificate_type": "end_entity", "ca_body": "", "ca_chain": [ { "cert_type": "intermediate", "blob": "", "common_name": "Example ICA" }, { "cert_type": "root", "blob": "", "common_name": "Example root" } ], "certificate_template": { "id": "f1b8aba9-3658-44f0-b11e-5f478b9c887f", "name": "Example certificate template" }, "scep_get_ca_cert_response_with_root": false, "scep_get_ca_cert_response_der_format": false, "scep_encryption_algorithm": "aes128WithCBC" } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/example-request": { "get": { "tags": [ "Enrollment profiles" ], "summary": "Get example certificate request by enrollment profile ID", "operationId": "getExampleCertificateRequestEnrollmentProfileID", "description": "Use this endpoint to get an example of the JSON request body for requesting certificates using the given enrollment profile.\n\nThe enrollment profile must use an enrollment method of API or PORTAL.\n", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "responses": { "200": { "description": "Example certificate request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestCertificateRequest" }, "example": { "enrollment_profile_id": "IOT_374599fd-beb1-45b3-91e4-26016463ce2f", "csr": "Provide your CSR", "certificate_profile_attributes": [ { "id": "subject.common_name", "value": "Provide your certificate field value" }, { "id": "subject.organization_name", "value": "Provide your certificate field value (optional)" }, { "id": "subject.country", "value": "Provide your certificate field value (optional)" }, { "id": "san.dns_name", "value": "Provide your certificate field value" } ], "device_attributes": [ { "id": "DEVICE_IDENTIFIER", "value": "Provide your device field value" }, { "id": "e9eb3c66-a2e5-433e-b5f3-e57deb3a5a14", "value": "Provide your device field value" }, { "id": "e2854683-660b-4794-a1ee-6a95bf3b13a9", "value": "Provide your device field value (optional)" } ], "response_with_certificate_only": false, "split_certificate_response": true, "include_certificate_chain": true, "server_side_key_gen": false } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "errors": [ { "code": "entity_not_found", "message": "Enrollment profile with id {invalid} does not exist" } ] } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "errors": [ { "code": "invalid_input", "message": "{message}" } ] } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `VIEW_IOT_ENROLLMENT_PROFILE` or `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "errors": [ { "code": "access_denied", "message": "Access denied" } ] } }, "internal_service_error": { "summary": "internal_server_error", "value": { "errors": [ { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } ] } } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}": { "get": { "tags": [ "Enrollment profiles" ], "description": "Use this endpoint to get details for an enrollment profile.", "operationId": "getEnrollmentProfile", "summary": "Get enrollment profile details", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentProfileResponse" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Enrollment profile with id {enrollment_profile_id} does not exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `VIEW_IOT_ENROLLMENT_PROFILE` or `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "put": { "tags": [ "Enrollment profiles" ], "description": "Use this endpoint to update an enrollment profile.\n* **To update a single field**, include a value only for the field you want to update.\n* **To set an empty value for a field**, set the value of the field to `null`.\n", "operationId": "updateEnrollmentProfile", "summary": "Update enrollment profile", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Enrollment profile name. Must not be `null`.", "example": "Updated name" }, "ica_id": { "type": "string", "description": "ID of the intermediate CA that issues certificates requested through the enrollment profile.", "example": "AAC2E2DD6BEAE2E5EE93954BAE15E34D" }, "allowed_ip_addresses": { "type": "array", "description": "List of IP addresses allowed to request certificates using the enrollment profile.", "example": [ "1.1.1.1", "2.2.2.2" ], "items": { "type": "string" } }, "certificate_profile_id": { "type": "string", "description": "ID of the certificate profile to use for certificates requested through the enrollment profile.", "example": "eb1ec97c-d0d6-4d66-ad29-af88fd86ab21" }, "timezone": { "type": "string", "description": "Region-based time zone ID for the `allowed_hours_from` and `allowed_hours_to` values. Format: `Area/Location` (for example, `America/New_York`). Accepts region names based on the Time Zone Database (tz database). See [list of tz database timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).\n", "example": "America/New_York" }, "allowed_hours_from": { "type": "string", "description": "Daily start time in the specified `timezone` (UTC if no `timezone` is set) for when certificates can be requested through the enrollment profile. Format: `HH:MM:SS`\n", "format": "date", "example": "09:45:00" }, "allowed_hours_to": { "type": "string", "description": "Daily end time in the specified `timezone` (UTC if no `timezone` is set) for when certificates can be requested through the enrollment profile. Format: `HH:MM:SS`\n", "format": "date", "example": "17:30:00" }, "valid_from": { "type": "string", "description": "Date the enrollment profile is valid from. Format: `YYYY-MM-DD`.\n", "example": "2021-06-25", "format": "date" }, "expires_on": { "type": "string", "description": "Date the enrollment profile expires. Format: `YYYY-MM-DD`.\n", "example": "2022-06-25", "format": "date" }, "require_approval_for_enroll": { "type": "boolean", "default": false, "description": "If true, a user with `APPROVE_IOT_CERTIFICATE` permissions must approve enrollment requests created with this enrollment profile. Otherwise, false (default).\n\nEnrollment requests pending approval appear in the list of requests in your account. DigiCert® IoT Trust Manager only issues the certificate when the request is approved.\n\nTo require approvals, the enrollment profile must use an enrollment method of `API` or `PORTAL`.\n", "example": true }, "require_approval_for_renew": { "type": "boolean", "default": false, "description": "If true, a user with `APPROVE_IOT_CERTIFICATE` permissions must approve renewal requests created with this enrollment profile. Otherwise, false (default).\n\nRenewal requests pending approval appear in the list of requests in your account. DigiCert® IoT Trust Manager only issues the certificate when the request is approved.\n\nTo require approvals, the enrollment profile must use an enrollment method of `API` or `PORTAL`.\n", "example": true }, "allow_key_cache": { "type": "boolean", "default": false, "description": "If true, when you request a certificate using server-side keypair generation, DigiCert IoT® Trust Manager caches the AES key that encrypts the returned keypair. Then, for a duration of your choosing (`key_cache_validity_period`), the same key encrypts keypairs returned by subsequent certificate requests. When this encryption key expires, the system generates a new one, which is cached for reuse in the same way.\n\nIf false (default), DigiCert IoT® Trust Manager generates a unique AES encryption key for each certificate request.\n\n**Note:** When `allow_key_cache` is true, `key_cache_validity_period_type` and `key_cache_validity_period` are required.\n" }, "key_cache_validity_period_type": { "type": "string", "description": "Unit of time for the key cache validity period. Required when `allow_key_cache` is true.\n", "example": "days", "enum": [ "days", "hours", "minutes", "seconds" ] }, "key_cache_validity_period": { "type": "string", "description": "Key cache validity period. Define unit of time measurement with `key_cache_validity_period_type`. Required when `allow_key_cache` is true.\n", "example": 1 }, "digest_email_notification_period": { "type": "string", "description": "Frequency of request notification emails for the enrollment profile.\n\nAllowed values:\n* `individual_request`: DigiCert® IoT Trust Manager sends an email each time a request is created.\n\n* `daily_digest`: DigiCert® IoT Trust Manager sends a daily email with the total number of pending requests.\n\n* `do_not_send`: DigiCert® IoT Trust Manager doesn't send request notification emails.\n", "enum": [ "individual_request", "daily_digest", "do_not_send" ] }, "approvers": { "type": "array", "description": "List of IDs for users that receive request notification emails for the enrollment profile. If empty, all users with `APPROVE_IOT_CERTIFICATE` permissions receive request notification emails.\n", "items": { "type": "string", "format": "uuid", "description": "User ID.", "example": "1cc6f662-f93c-4a7e-a8e3-2829c8cf05be" } }, "notification_email_list": { "type": "array", "description": "List of additional email addresses that receive request notifications.\n", "items": { "type": "string", "description": "Email address.", "example": "example.com" } }, "scep_get_ca_cert_response_with_root": { "type": "boolean", "description": "Option to include root CA to GetCACert operation response. Only available for SCEP enrollment method.\n" }, "scep_get_ca_cert_response_der_format": { "type": "boolean", "description": "When set to true we force GetCACert operation response content type header to application/x-x509-ca-cert. Only available for SCEP enrollment method.\n" }, "scep_encryption_algorithm": { "type": "string", "description": "Encryption algorithm to use for response encryption. Default aes128WithCBC.\n" } } } } } }, "responses": { "200": { "description": "Enrollment profile successfully updated. Always returns the full JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentProfileResponse" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Enrollment profile with id {enrollment_profile_id} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "Certificate profile with id {certificate_profile_id} does not exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/assignable-ca": { "get": { "tags": [ "Enrollment profiles" ], "operationId": "listAssignableICAs", "description": "Use this endpoint to get a list of issuing ICAs you can assign to an enrollment profile.", "summary": "List assignable ICAs", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" }, { "in": "query", "name": "limit", "description": "Number of records to include in the result. Maximum: 1000\n", "example": 10, "schema": { "type": "number", "maximum": 10000 } }, { "in": "query", "name": "offset", "description": "Index of first record to return.", "example": 10, "schema": { "default": 0, "type": "number" } }, { "in": "query", "name": "name", "description": "Optional name filter. Record will be returned if record name contains search text.", "example": "ICA name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of objects with information about ICAs you can assign to the enrollment profile.", "items": { "$ref": "#/components/schemas/icaDetails" } } } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Enrollment profile with id {enrollment_profile_id} does not exist" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `VIEW_IOT_ENROLLMENT_PROFILE` or `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/issuer": { "get": { "tags": [ "Enrollment profiles" ], "operationId": "getIssuingICA", "description": "Use this endpoint to get the issuing ICA for an enrollment profile.", "summary": "Get issuing ICA", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" }, { "in": "query", "name": "include_chain", "description": "If true, response includes the full certificate chain (ICAs and root certificate) for the enrollment profile's issuing ICA. If false (default), response only includes the issuing ICA certificate.", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "Object with issuing ICA details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "PEM-encoded certificate data for the issuing ICA certificate.", "example": "" }, "type": { "description": "Certificate type: root or intermediate.\n", "type": "string", "enum": [ "intermediate", "root" ] }, "chain": { "type": "array", "description": "List of objects containing the intermediate CA and root certificates in the certificate chain. Each certificate in the `chain` array is signed by the certificate in the object that follows it. Only returned if request URL includes the query string `include_chain=true`.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "type": { "type": "string", "description": "Certificate type: root or intermediate.\n", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "body": { "type": "string", "description": "PEM-encoded certificate data.", "example": "" } } } } } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Enrollment profile with id {enrollment_profile_id} does not exist" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/enrollment-specification": { "get": { "tags": [ "Enrollment profiles" ], "description": "Use this endpoint to get information about the fields used during enrollment for a specific enrollment profile.\n\n**Note:** This endpoint is only supported for enrollment profiles that use the API or PORTAL enrollment methods.\n", "summary": "Get enrollment profile specification", "operationId": "getEnrollmentProfileSpecification", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "description": "List of objects with details about the fields used for the enrollment profile.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the field. Use this ID to specify a value for the field during certificate enrollment.", "example": "signature_algorithm" }, "name": { "type": "string", "description": "Display name for the field.", "example": "signature_algorithm" }, "type": { "type": "string", "description": "Field type.\n- `CERTIFICATE` — Submit the value for this field in the `certificate_profile_attributes` section of your enrollment request.\n- `USER` — Submit the value for this field in the `device_attributes` section of your enrollment request.\n", "example": "CERTIFICATE", "enum": [ "CERTIFICATE", "USER" ] }, "mandatory": { "type": "boolean", "description": "Whether the field is required. If `true` and the field does not have a `default_value`, you must provide a value for this field when you submit an enrollment request.", "example": true }, "editable": { "type": "boolean", "description": "Whether users can provide a custom value for the field during enrollment. If `false`, the value is extracted from the certificate signing request (CSR) or from enrollment source mapping. Alternatively, the `default_value` is used.", "example": false }, "update_from_csr": { "type": "boolean", "description": "Whether the value for this field is extracted from the CSR during enrollment.", "example": false }, "value_type": { "type": "object", "description": "Object that describes the type of values the field accepts.", "properties": { "type": { "type": "string", "description": "Type of data the field accepts.", "enum": [ "string", "number" ] }, "options": { "type": "boolean", "description": "Whether the allowed values for this field are limited to a list of options (returned in the `options` array).", "example": true }, "multiple": { "type": "boolean", "description": "Describes whether a user can provide more than one value for the field. If `true`, you can submit an array of values for this field during enrollment. Otherwise, you must submit a single value.", "example": false } } }, "options": { "type": "array", "description": "A list of the allowed values for this field. Only returned when `value_type.options` is `true`.", "items": { "type": "string" }, "example": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "match_issuer" ] }, "default_value": { "description": "The default value for the field. The type for this value depends on the `value_type` details. It may be a single string, a single number, or an array.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array" } ], "example": "match_issuer" } } } } } }, "example": { "fields": [ { "id": "csr", "name": "csr", "type": "CERTIFICATE", "mandatory": true, "editable": true, "update_from_csr": false, "value_type": { "type": "string", "options": false, "multiple": false } }, { "id": "signature_algorithm", "name": "signature_algorithm", "type": "CERTIFICATE", "mandatory": true, "editable": false, "update_from_csr": false, "value_type": { "type": "string", "options": true, "multiple": false }, "default_value": "match_issuer", "options": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "match_issuer" ] }, { "id": "subject.common_name", "name": "subject_common_name", "type": "CERTIFICATE", "mandatory": true, "editable": true, "update_from_csr": true, "value_type": { "type": "string", "options": false, "multiple": false } }, { "id": "subject.organization_name", "name": "subject_organization", "type": "CERTIFICATE", "mandatory": true, "editable": true, "update_from_csr": true, "value_type": { "type": "string", "options": false, "multiple": false } }, { "id": "validity.duration_unit", "name": "duration_unit", "type": "CERTIFICATE", "mandatory": true, "editable": false, "update_from_csr": false, "value_type": { "type": "string", "options": true, "multiple": false }, "default_value": "months", "options": [ "days", "months", "years" ] }, { "id": "validity.duration_value", "name": "duration_value", "type": "CERTIFICATE", "mandatory": true, "editable": false, "update_from_csr": false, "value_type": { "type": "number", "options": false, "multiple": false }, "default_value": 7 }, { "id": "DEVICE_IDENTIFIER", "name": "Device Identifier", "type": "USER", "mandatory": true, "editable": false, "update_from_csr": false, "value_type": { "type": "string", "options": false, "multiple": false }, "default_value": "Provided from subject.common_name" }, { "id": "7a2ad21e-38da-4d22-b81a-d94a71f6ae64", "name": "party-no", "type": "USER", "mandatory": true, "editable": false, "update_from_csr": false, "value_type": { "type": "string", "options": false, "multiple": false }, "default_value": "Provided from subject.organization_name" } ] } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "entity_not_found": { "summary": "entity_not_found", "value": { "code": "entity_not_found", "message": "Enrollment profile with id {enrollment_profile_id} does not exist" } }, "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/status": { "get": { "operationId": "getEnrollmentProfileStatus", "summary": "Get enrollment profile status", "tags": [ "Enrollment profiles" ], "description": "Use this endpoint to get the status (`ACTIVE`, `DISABLED`, `DELETED`) of the enrollment profile with the given ID.\n\n## Authenticate with enrollment profile credentials\n\nThis endpoint supports the option to authenticate with the enrollment passcode or authentication certificate for the given enrollment profile. This is especially useful for API clients that don't have access to an API token or client authentication certificate from DigiCert@ Account Manager. API clients can use the same credentials they use for enrollment to check the status of an enrollment profile before requesting a certificate.\n", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "responses": { "200": { "description": "Enrollment profile status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Enrollment profile status.", "example": "ACTIVE", "enum": [ "ACTIVE", "DELETED", "DISABLED" ] } } } } } } } } }, "/v1/passcode": { "get": { "tags": [ "Enrollment profile passcodes" ], "description": "Use this endpoint to get a list of enrollment profile passcodes.\n", "operationId": "listEnrollmentPasscodes", "summary": "List enrollment passcodes", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to enrollment passcodes for the account with the given ID.\n", "schema": { "type": "string", "example": "9b7679fa-b1eb-4571-b805-f5a8cc8b520d", "format": "uuid" } }, { "in": "query", "name": "division_id", "description": "Limits results to enrollment passcodes for the division with the given ID.\n", "schema": { "type": "string", "example": "591c31d2-6b80-455b-95e9-4234aa0c5be7", "format": "uuid" } }, { "in": "query", "name": "name", "description": "Limits results to enrollment passcodes with a name that contains the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "Example enrollment passcode" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to enrollment passcodes for the enrollment profile with the given ID.\n", "schema": { "type": "string", "example": "IOT_d6b4d0c0-db1a-4d70-83b7-1ccf2f01af7a" } }, { "in": "query", "name": "enrollment_profile_name", "description": "Limits results to enrollment passcodes for enrollment profiles with a name that contains the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "Example enrollment profile" } }, { "in": "query", "name": "device_profile_id", "description": "Limits results to enrollment passcodes for a device profile with the given ID.\n", "schema": { "$ref": "#/components/schemas/device_profile_id" } }, { "in": "query", "name": "created_from", "description": "Limits results to enrollment passcodes created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to enrollment passcodes created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2022-06-30" } }, { "in": "query", "name": "usage_limit_from", "description": "Limits results to enrollment passcodes with a usage limit higher than the given number. Inclusive.\n", "schema": { "type": "integer", "example": 10 } }, { "in": "query", "name": "usage_limit_to", "description": "Limits results to enrollment passcodes with a usage limit lower than the given number. Inclusive.\n", "schema": { "type": "integer", "example": 10 } }, { "in": "query", "name": "expires_from", "description": "Limits results to enrollment passcodes that expire after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2023-12-12" } }, { "in": "query", "name": "expires_to", "description": "Limits results to enrollment passcodes that expire before the given date Format: `YYYY-MM-DD`\n", "schema": { "format": "date-time", "type": "string", "example": "2025-12-12" } }, { "in": "query", "name": "status", "description": "Limits results to enrollment passcodes with the given status.\n", "schema": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "username", "description": "Limits results to enrollment passcodes for users with a username that contains the given string.\n", "schema": { "type": "string", "example": "john_doe" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending (`ASC`) or descending (`DESC`) order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "default": "DESC", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of enrollment passcodes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of enrollment passcodes .", "items": { "$ref": "#/components/schemas/enrollmentPasscodeObject" } } } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "Please provide a unique passcode name" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/passcode": { "post": { "tags": [ "Enrollment profile passcodes" ], "description": "Use this endpoint to create a unique passcode for authenticating orders associated with an enrollment profile in your account. To create an enrollment passcode, the enrollment profile must use the EST, SCEP, or CMPv2 enrollment method.\n\nYou can create multiple passcodes for a single enrollment profile, each with a different validity period or usage limit. Each passcode must have a unique name within the enrollment profile.\n\nEnrollment profiles that use the EST or CMPv2 enrollment methods support the option to associate a username with enrollment passcodes. To add a username, include the `enable_username_for_passcode` and `username` parameters in the body of your request.\n", "operationId": "createEnrollmentPasscode", "summary": "Create enrollment passcode", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createEnrollmentPasscodeRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" } ], "responses": { "201": { "description": "Passcode details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentPasscodeObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "Please provide a unique passcode name" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/passcode/{passcode_id}": { "get": { "tags": [ "Enrollment profile passcodes" ], "description": "Use this endpoint to get information about an enrollment passcode with the given ID.", "summary": "Get enrollment passcode details", "operationId": "getEnrollmentPasscodeDetails", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" }, { "$ref": "#/components/parameters/passcode_id" } ], "responses": { "200": { "description": "Enrollment passcode details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentPasscodeObject" } } } } } }, "put": { "tags": [ "Enrollment profile passcodes" ], "description": "Use this endpoint to update an enrollment passcode.\n\n**Note**: This operation is destructive. The values in your request overwrite existing values. Omitting a property from the request clears any value already set for that property.\n", "summary": "Update enrollment passcode", "operationId": "updateEnrollmentPasscode", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/createEnrollmentPasscodeRequest" } ], "anyOf": [ { "type": "object", "properties": { "generation_option": { "type": "string", "description": "If `AUTO` (default), DigiCert® IoT Trust Manager generates the passcode for you. If `PROVIDED`, use the `passcode` request parameter to provide your own passcode.\n", "enum": [ "AUTO", "PROVIDED" ] } } } ], "example": { "name": "Passcode name", "description": "Custom passcode description.", "enable_username_for_passcode": true, "username": "username_example", "passcode_length": 27, "usage_limit": 100, "validity_period": { "from": "2021-01-01", "to": "2021-06-01" }, "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "string" } ] } } } } }, "responses": { "200": { "description": "Passcode successfully updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enrollmentPasscodeObject" } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "Please provide a unique passcode name" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "delete": { "tags": [ "Enrollment profile passcodes" ], "operationId": "deleteEnrollmentPasscode", "description": "Use this endpoint to set the status of an enrollment profile passcode to `DELETED`. Deleting an enrollment passcode does not permanently remove the passcode record, and `DELETED` passcodes can be restored.\n", "summary": "Delete enrollment passcode", "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" }, { "$ref": "#/components/parameters/passcode_id" } ], "responses": { "204": { "description": "No content." } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/passcode/{passcode_id}/undelete": { "put": { "summary": "Restore enrollment passcode", "operationId": "restoreEnrollmentPasscode", "description": "Use this endpoint to restore a deleted enrollment passcode.", "tags": [ "Enrollment profile passcodes" ], "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" }, { "$ref": "#/components/parameters/passcode_id" } ], "responses": { "204": { "description": "No content." } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/passcode/{passcode_id}/disable": { "put": { "summary": "Disable enrollment passcode", "operationId": "disableEnrollmentPasscode", "description": "Use this endpoint to disable an enrollment passcode.", "tags": [ "Enrollment profile passcodes" ], "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" }, { "$ref": "#/components/parameters/passcode_id" } ], "responses": { "204": { "description": "No content." } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/passcode/{passcode_id}/enable": { "put": { "summary": "Enable enrollment passcode", "operationId": "enableEnrollmentPasscode", "description": "Use this endpoint to enable an enrollment passcode.", "tags": [ "Enrollment profile passcodes" ], "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" }, { "$ref": "#/components/parameters/passcode_id" } ], "responses": { "204": { "description": "No content." } } } }, "/v1/enrollment-profile/{enrollment_profile_id}/passcode/{passcode_id}/regenerate": { "put": { "summary": "Regenerate enrollment passcode", "operationId": "regenerateEnrollmentPasscode", "description": "Use this endpoint to regenerate an enrollment passcode.\n\n**Note:** You can only regenerate passcodes originally generated by DigiCert® IoT Trust Manager (`generation_option` = `AUTO`). To change a user-provided passcode (`generation_option` = `PROVIDED`), use the **Update enrollment passcode** API request and submit a new `passcode` value.\n", "tags": [ "Enrollment profile passcodes" ], "parameters": [ { "$ref": "#/components/parameters/enrollment_profile_id" }, { "$ref": "#/components/parameters/passcode_id" } ], "responses": { "204": { "description": "No content." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. You can only regenerate passcodes originally generated by DigiCert® IoT Trust Manager.", "value": { "errors": [ { "code": "invalid_input", "message": "Only generated initially passcode can be regenerated" } ] } } } } } } } } }, "/v1/acme-authentication": { "post": { "summary": "Add ACME authentication credentials", "description": "Use this endpoint to add ACME credentials to your DigiCert® IoT Trust Manager account and assign them to an enrollment profile that supports the ACME enrollment method.\n\n**Note:** You can use this endpoint to add ACME credentials without assigning them to an enrollment profile. However, you cannot use it to assign ACME credentials that you already added to your account. If you do not assign ACME credentials to an enrollment profile when you add them, you can assign them later by signing in to your DigiCert® IoT Trust Manager account.\n\n**Adding ACME credentials**\n\nThis endpoint supports two options for adding ACME credentials:\n* **Upload an existing certificate or public key to your account.** To use this option, you must have a certificate or public key that corresponds to an existing private key for your ACME client.\n* **Create a new key identifier (KID) and keyed-hash message authentication code (HMAC).** Use these credentials to register your DigiCert® IoT Trust Manager account with an ACME client that supports external account binding.\n\n**Important!** We only display the KID and HMAC once. There is no way to recover lost ACME credentials. If you ever lose your ACME credentials, revoke them and generate new ones.\n\n**Assigning ACME credentials to an enrollment profile**\n\nWhen you add ACME credentials to an account, you can assign them to an enrollment profile that supports the ACME enrollment method. When you assign ACME credentials, you can:\n\n* Limit how many times the credentials can be used to request a certificate with the enrollment profile.\n* Define start and end dates for when the credentials can be used with the enrollment profile.\n* Define values that certificate fields must contain when using the credentials to request a certificate with the enrollment profile.\n", "tags": [ "ACME" ], "operationId": "createAcmeAuthentication", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createAcmeAuthenticationRequest" }, "examples": { "new_eab_credentials": { "summary": "New EAB credentials", "description": "Example request to create a new KID and HMAC key for external account binding.", "value": { "name": "Example ACME credentials", "description": "Example description", "account_id": "f92834ce-cdea-1584-b154-193bb198345e", "enrollment_profile": "IOT_07ccbdc1-35d9-6ba2-7d3b-197b2c456088", "external_account_binding": true, "usage_limit": 10, "start_date": "2021-03-05", "end_date": "2022-03-05", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "example1" }, { "certificate_field": "subject.organization_units", "matcher": "equals", "value": [ "example1", "example2" ] } ] } }, "upload_public_key": { "summary": "Upload certificate or public key", "description": "Example request to upload a certificate or public key that corresponds to an existing private key for your ACME client.", "value": { "name": "Example ACME credentials", "description": "Example description", "account_id": "f92834ce-cdea-1584-b154-193bb198345e", "authentication_pem": "-----BEGIN PUBLIC KEY-----...", "enrollment_profile": "IOT_07ccbdc1-35d9-6ba2-7d3b-197b2c456088", "usage_limit": 10, "start_date": "2021-03-05", "end_date": "2022-03-05", "registered_values": [ { "certificate_field": "subject.common_name", "matcher": "equals", "value": "example1" }, { "certificate_field": "subject.organization_units", "matcher": "equals", "value": [ "example1", "example2" ] } ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/acmeAuthenticationResponseObject" }, "examples": { "new_eab_credentials": { "summary": "New EAB credentials", "description": "Example response when creating a new KID and HMAC key for external account binding.", "value": { "id": "f92834ce-cdea-1584-b154-193bb198345e", "name": "Example ACME Credentials", "description": "Test", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "status": "ACTIVE", "created_at": "2021-02-18T21:02:15.285249Z", "hmac_key": "FS3f8Q7yUZQQO4uLUP8vAyREMCKyUqRr7JoHy1aquKiPYwu42r67CcELWlYRy9oJyzJ09n5oojJzz9t0EhWiNQ", "external_account_binding": true, "account_bind": false } }, "upload_public_key": { "summary": "Upload certificate or public key", "description": "Example response when uploading a certificate or public key that corresponds to an existing private key for your ACME client.", "value": { "id": "f92834ce-cdea-1584-b154-193bb198345e", "name": "Example", "description": "Example", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "authentication_pem": "-----BEGIN CERTIFICATE-----...", "authentication_type": "certificate", "thumbprint": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143", "status": "ACTIVE", "created_at": "2021-02-18T20:43:01.850786Z", "key_type": "RSA", "rsa_key_size": 2048, "key_description": "RSA 2048", "certificate_common_name": "Example Common Name", "issuer_common_name": "Example Issuing CA", "external_account_binding": false, "account_bind": true, "public_key_pem": "-----BEGIN PUBLIC KEY-----..." } } } } } }, "default": { "description": "Error message examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" }, "examples": { "invalid_input": { "summary": "invalid_input", "description": "Bad request. A required parameter is missing or a value is not valid.", "value": { "code": "invalid_input", "message": "{message}" } }, "access_denied": { "summary": "access_denied", "description": "Access denied due to an invalid API key, missing `MANAGE_IOT_ENROLLMENT_PROFILE` permission, or another authentication issue.", "value": { "code": "access_denied", "message": "Access denied" } }, "internal_service_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal server error. Check logs for details" } } } } } } } }, "get": { "summary": "List ACME authentication credentials", "description": "Use this endpoint to get a list of ACME authentication credentials. Use query parameters to filter results or search for a specific set of credentials.\n", "tags": [ "ACME" ], "operationId": "listAcmeAuthentication", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to ACME authentication credentials for the account with the given ID.\n", "schema": { "type": "string", "format": "uuid", "example": "35f4c985-4480-4ade-93c7-c9cd178b1133" } }, { "in": "query", "name": "name", "description": "Limits results to ACME authentication credentials with a name that contains the given string. Case-insensitive.\n", "schema": { "type": "string", "example": "example_name" } }, { "in": "query", "name": "created_at_from", "description": "Limits results to ACME authentication credentials created **after** the given date and time (UTC). Use with `created_at_to` to search for credentials with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "created_at_to", "description": "Limits results to ACME authentication credentials created **before** the given date and time (UTC). Use with `created_at_from` to search for credentials with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "type", "description": "Limits results to ACME authentication credentials with the given `authentication_type`.\n", "schema": { "type": "string", "example": "public_key", "enum": [ "certificate", "public_key" ] } }, { "in": "query", "name": "certificate_common_name", "description": "Limits results to ACME authentication credentials with a `certificate_common_name` containing the given string.", "schema": { "type": "string", "example": "Common Name Example" } }, { "in": "query", "name": "issuer_common_name", "description": "Limits results to ACME authentication credentials with an `issuer_common_name` containing the given string.", "schema": { "type": "string", "example": "Issuer Common Name Example" } }, { "in": "query", "name": "status", "description": "Limits results to ACME authentication credentials with the given status. Case-insensitive.\n", "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to ACME authentication credentials assigned to specific enrollment profile with id `enrollment_profile_id`.", "schema": { "type": "string", "example": "IOT_5c2a18ff-f93c-4ea5-9a61-86a977af7406" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "default": "created_at", "type": "string", "enum": [ "name", "status", "created_at", "account_id", "certificate_common_name", "issuer_common_name" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "default": "DESC", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of ACME authentication credential objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "Array of ACME authentication credentials.\n", "uniqueItems": true, "items": { "allOf": [ { "$ref": "#/components/schemas/acmeAuthenticationResponseObject" }, { "type": "object", "properties": { "enrollment_profiles_assigned": { "type": "integer", "description": "Number of enrollment profiles to which the ACME authentication credentials are assigned.", "example": 1 } } } ] } } } }, "example": { "limit": 20, "offset": 0, "pagination": true, "next": false, "total": 2, "records": [ { "id": "f92834ce-cdea-1584-b154-193bb198345e", "name": "Example ACME Credentials", "description": "Test", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "status": "ACTIVE", "created_at": "2021-02-18T21:02:15.285249Z", "hmac_key": "FS3f8Q7yUZQQO4uLUP8vAyREMCKyUqRr7JoHy1aquKiPYwu42r67CcELWlYRy9oJyzJ09n5oojJzz9t0EhWiNQ", "external_account_binding": true, "account_bind": false, "enrollment_profiles_assigned": 1 }, { "id": "f92834ce-cdea-1584-b154-193bb198345e", "name": "Example", "description": "Example", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "authentication_pem": "-----BEGIN CERTIFICATE-----...", "authentication_type": "certificate", "thumbprint": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143", "status": "ACTIVE", "created_at": "2021-02-18T20:43:01.850786Z", "key_type": "RSA", "rsa_key_size": 2048, "key_description": "RSA 2048", "certificate_common_name": "Example Common Name", "issuer_common_name": "Example Issuing CA", "external_account_binding": false, "account_bind": true, "public_key_pem": "-----BEGIN PUBLIC KEY-----...", "enrollment_profiles_assigned": 1 } ] } } } } } } }, "/v1/acme-authentication/{acme_authentication_id}": { "get": { "summary": "Get ACME authentication credential details", "description": "Use this endpoint to get information about the ACME authentication credentials with the given ID.\n", "tags": [ "ACME" ], "operationId": "getAcmeAuthentication", "parameters": [ { "in": "path", "required": true, "name": "acme_authentication_id", "description": "ID of ACME authentication credentials.", "schema": { "type": "string", "format": "uuid", "example": "e219cf92-2c55-437d-aebd-71ce0df07378" } } ], "responses": { "200": { "description": "ACME authentication credential details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/acmeAuthenticationResponseObject" }, "examples": { "eab_credentials": { "summary": "External account binding (EAB) ACME credentials", "description": "ACME credentials created by generating a key identifier and keyed-hash message authentication code and registering your account with an ACME client that supports external account binding.", "value": { "id": "f92834ce-cdea-1584-b154-193bb198345e", "name": "Example ACME Credentials", "description": "Test", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "status": "ACTIVE", "created_at": "2021-02-18T21:02:15.285249Z", "hmac_key": "FS3f8Q7yUZQQO4uLUP8vAyREMCKyUqRr7JoHy1aquKiPYwu42r67CcELWlYRy9oJyzJ09n5oojJzz9t0EhWiNQ", "external_account_binding": true, "account_bind": false } }, "upload_public_key": { "summary": "Upload certificate or public key", "description": "ACME credentials created from a certificate or public key corresponding to an existing private key for your ACME client.", "value": { "id": "f92834ce-cdea-1584-b154-193bb198345e", "name": "Example", "description": "Example", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "authentication_pem": "-----BEGIN CERTIFICATE-----...", "authentication_type": "certificate", "thumbprint": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143", "status": "ACTIVE", "created_at": "2021-02-18T20:43:01.850786Z", "key_type": "RSA", "rsa_key_size": 2048, "key_description": "RSA 2048", "certificate_common_name": "Example Common Name", "issuer_common_name": "Example Issuing CA", "external_account_binding": false, "account_bind": true, "public_key_pem": "-----BEGIN PUBLIC KEY-----..." } } } } } } } }, "put": { "summary": "Update ACME authentication credentials", "description": "Use this endpoint to change the friendly name of the ACME authentication credentials with the given ID.\n", "operationId": "updateAcmeAuthentication", "tags": [ "ACME" ], "parameters": [ { "in": "path", "required": true, "name": "acme_authentication_id", "description": "ID of ACME authentication credentials.", "schema": { "type": "string", "format": "uuid", "example": "e219cf92-2c55-437d-aebd-71ce0df07378" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New friendly name for ACME authentication credentials.", "maxLength": 255, "example": "New name" } } } } } }, "responses": { "200": { "description": "ACME authentication credential details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/acmeAuthenticationResponseObject" }, "examples": { "eab_credentials": { "summary": "External account binding (EAB) ACME credentials", "description": "ACME credentials created by generating a key identifier and keyed-hash message authentication code and registering your account with an ACME client that supports external account binding.", "value": { "id": "f92834ce-cdea-1584-b154-193bb198345e", "name": "Example ACME Credentials", "description": "Test", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "status": "ACTIVE", "created_at": "2021-02-18T21:02:15.285249Z", "hmac_key": "FS3f8Q7yUZQQO4uLUP8vAyREMCKyUqRr7JoHy1aquKiPYwu42r67CcELWlYRy9oJyzJ09n5oojJzz9t0EhWiNQ", "external_account_binding": true, "account_bind": false } }, "upload_public_key": { "summary": "Upload certificate or public key", "description": "ACME credentials created from a certificate or public key corresponding to an existing private key for your ACME client.", "value": { "id": "f92834ce-cdea-1584-b154-193bb198345e", "name": "Example", "description": "Example", "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e", "authentication_pem": "-----BEGIN CERTIFICATE-----...", "authentication_type": "certificate", "thumbprint": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143", "status": "ACTIVE", "created_at": "2021-02-18T20:43:01.850786Z", "key_type": "RSA", "rsa_key_size": 2048, "key_description": "RSA 2048", "certificate_common_name": "Example Common Name", "issuer_common_name": "Example Issuing CA", "external_account_binding": false, "account_bind": true, "public_key_pem": "-----BEGIN PUBLIC KEY-----..." } } } } } } } } }, "/v1/acme-authentication/{acme_authentication_id}/disable": { "put": { "summary": "Disable ACME authentication credentials", "description": "Use this endpoint to disable the ACME authentication credentials with the given ID. Disabled ACME authentication credentials cannot be used.\n", "operationId": "disableAcmeAuthentication", "tags": [ "ACME" ], "parameters": [ { "in": "path", "required": true, "name": "acme_authentication_id", "description": "ID of ACME authentication credentials.", "schema": { "type": "string", "format": "uuid", "example": "e219cf92-2c55-437d-aebd-71ce0df07378" } } ], "responses": { "204": { "description": "ACME authentication credentials disabled. No content." } } } }, "/v1/acme-authentication/{acme_authentication_id}/enable": { "put": { "summary": "Enable ACME authentication credentials", "description": "Use this endpoint to enable the ACME authentication credentials with the given ID.\n", "operationId": "enableAcmeAuthentication", "tags": [ "ACME" ], "parameters": [ { "in": "path", "required": true, "name": "acme_authentication_id", "description": "ID of ACME authentication credentials.", "schema": { "type": "string", "format": "uuid", "example": "e219cf92-2c55-437d-aebd-71ce0df07378" } } ], "responses": { "204": { "description": "ACME authentication credentials enabled. No content." } } } }, "/v1/acme-authentication/{acme_authentication_id}/delete": { "put": { "summary": "Delete ACME authentication credentials", "description": "Use this endpoint to delete the ACME authentication credentials with the given ID. Deleted ACME authentication credentials cannot be used.\n", "operationId": "deleteAcmeAuthentication", "tags": [ "ACME" ], "parameters": [ { "in": "path", "required": true, "name": "acme_authentication_id", "description": "ID of ACME authentication credentials.", "schema": { "type": "string", "format": "uuid", "example": "e219cf92-2c55-437d-aebd-71ce0df07378" } } ], "responses": { "204": { "description": "ACME authentication credentials deleted. No content." } } } }, "/v1/acme-authentication/{acme_authentication_id}/undelete": { "put": { "summary": "Restore ACME authentication credentials", "description": "Use this endpoint to restore the deleted ACME authentication credentials with the given ID.\n", "operationId": "restoreAcmeAuthentication", "tags": [ "ACME" ], "parameters": [ { "in": "path", "required": true, "name": "acme_authentication_id", "description": "ID of ACME authentication credentials.", "schema": { "type": "string", "format": "uuid", "example": "e219cf92-2c55-437d-aebd-71ce0df07378" } } ], "responses": { "204": { "description": "ACME authentication credentials restored. No content." } } } }, "/v1/managed-ca/{ica_id}": { "get": { "tags": [ "ICAs" ], "summary": "Get ICA details", "operationId": "getICA", "description": "Use this endpoint to get information about an intermediate CA (ICA) used in DigiCert® IoT Trust Manager.\n", "parameters": [ { "in": "path", "name": "ica_id", "required": true, "description": "Intermediate CA ID.", "schema": { "type": "string", "example": "01777FAA99199EFF90981078994EDD91" } } ], "responses": { "200": { "description": "Object with intermediate CA details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/managedCA" } } } } } } }, "/v1/managed-ca": { "get": { "tags": [ "ICAs" ], "summary": "List ICAs", "description": "Use this endpoint to get a list of intermediate CAs (ICAs) used in DigiCert® IoT Trust Manager. Use query parameters to filter results or search for a specific ICA.\n", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to ICAs for an account with the given ID.\n", "schema": { "type": "string", "example": "2b687cce-6739-4cef-92bf-156be48507a0" } }, { "in": "query", "name": "division_id", "description": "Limits results to ICAs for a division with the given ID.\n", "schema": { "type": "string", "example": "63c999ef-d4a0-4dd8-a7fc-e14ebe0167c5" } }, { "in": "query", "name": "common_name", "description": "Limits results to ICAs with the given common name.\n", "schema": { "type": "string", "example": "ICA common name" } }, { "in": "query", "name": "serial_number", "description": "Limits results to ICAs with the given serial number.\n", "schema": { "type": "string", "example": "" } }, { "in": "query", "name": "include_pem_ca_body", "description": "If true (default), each returned ICA record includes a `body` field with the PEM-formatted ICA certificate body. If false, ICA records omit the `body` field.", "schema": { "type": "boolean", "example": true, "default": true } }, { "in": "query", "name": "include_pem_ca_chain", "description": "If true (default), each returned ICA record includes a `chain` field containing details about each certificate in the ICA certificate chain. If false, ICA records omit the `chain` field.", "schema": { "type": "boolean", "example": true, "default": true } }, { "in": "query", "name": "valid_from_from", "description": "Limits results to ICAs with a `valid_from` value on or after the given date or date-time. Use with `valid_from_to` to search for ICAs with a `valid_from` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_from_to", "description": "Limits results to ICAs with a `valid_from` value on or before the given date or date-time. Use with `valid_from_from` to search for ICAs with a `valid_from` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_to_from", "description": "Limits results to ICAs with a `valid_to` value on or after the given date or date-time. Use with `valid_to_to` to search for ICAs with a `valid_to` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "valid_to_to", "description": "Limits results to ICAs with a `valid_to` value on or before the given date or date-time. Use with `valid_to_from` to search for ICAs with a `valid_to` date in a specific range. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. If not provided, results are sorted in descending order by date created (`created_at`).\n", "schema": { "type": "string", "enum": [ "created_at", "valid_from", "valid_to", "common_name", "serial_number", "id" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20, "example": 1 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of ICAs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of device profile records.", "items": { "oneOf": [ { "$ref": "#/components/schemas/managedCA" } ] } } } } } } } } } }, "/v1/certificate-template": { "get": { "tags": [ "Certificate templates" ], "summary": "List certificate templates", "operationId": "listCertificateTemplates", "description": "Use this endpoint to get a list of certificate templates, or to search for certificate templates that meet the given criteria.\n", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to certificate templates assigned to an account ID that is an exact match for the given ID.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "name", "description": "Limits results to certificate templates with a name that contains the given string.\n", "schema": { "type": "string", "example": "certificate_template_name" } }, { "in": "query", "name": "created_from", "description": "Limits results to certificate templates created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to certificate templates created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "status", "description": "Limits results to certificate templates with the given status. By default, deleted templates do not appear in the results. To search for deleted templates, use `status=DELETED`.\n", "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "type", "description": "Limits results to certificate templates of the given type.\n", "schema": { "type": "string", "enum": [ "custom", "system" ] } }, { "in": "query", "name": "limit_by_account", "description": "Limits results to certificate templates that are either limited to specific accounts (true) or not limited (false).\n", "schema": { "type": "boolean" } }, { "in": "query", "name": "format", "description": "Limits results to certificate templates for the given format.\n", "schema": { "type": "string", "enum": [ "x509", "global-platform", "attribute-certificate" ] } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. Default `sort_by` property is `created_at`.\n", "schema": { "type": "string", "enum": [ "id", "name", "created_at", "status", "type", "limit_by_accounts", "certificate_type" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 1000, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of certificate templates that meet the search criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "Array of certificate template records. Each record is an object that provides information about a certificate template in your DigiCert® IoT Trust Manager account.", "items": { "$ref": "#/components/schemas/certificateTemplateResponse" } } } }, "example": { "limit": 20, "offset": 0, "pagination": true, "next": false, "total": 1, "records": [ { "id": "5eda32f3-26e3-4c94-8826-4da221e0d7e8", "name": "Client Auth Example", "created_at": "2022-06-09T11:04:29Z", "body": { "key_types": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ], "issue_types": [ "client_authentication", "server_authentication" ], "signature_algorithm": { "allowed_algorithms": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA", "match_issuer" ], "default_algorithm": "match_issuer" }, "subject": { "attributes": [ { "type": "common_name", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "organization_name", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "organization_unit", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "street_address", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "postal_code", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "locality", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "state", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "country", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "email", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] } ] }, "extensions": { "key_usage": { "critical": true, "allow_critical_override": true, "required_usages": { "rsa": [ "digital_signature", "non_repudiation", "key_encipherment", "data_encipherment" ], "ecdsa": [ "digital_signature", "non_repudiation", "key_agreement" ] }, "optional_usages": { "rsa": [ "digital_signature", "non_repudiation", "key_encipherment", "data_encipherment" ], "ecdsa": [ "digital_signature", "non_repudiation", "key_agreement" ] } }, "extended_key_usage": { "critical": true, "allow_critical_override": true, "include": "optional", "required_usages": [ { "oid": "client_authentication", "name": "" } ], "optional_usages": [ { "oid": "server_authentication", "name": "" }, { "oid": "code_signing", "name": "" }, { "oid": "email_protection", "name": "" }, { "oid": "smart_card_logon", "name": "" } ] }, "san": { "critical": false, "dns_name": { "include": "no", "auto_include_cn": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, "user_principal_name": { "include": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, "email": { "include": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] } } }, "renewal_settings": { "renew_valid_cert": "anytime", "renew_expired_cert": "anytime", "renew_revoked_cert": true, "renewal_key_pair": "optional", "allow_override_renewal_key_pair": true }, "serial_number_size": 20, "validity": { "min_duration": { "value": 10, "unit": "DAYS" }, "max_duration": { "value": 5, "unit": "YEARS" }, "default_duration": { "min": { "value": 10, "unit": "DAYS" }, "max": { "value": 5, "unit": "YEARS" } } } }, "status": "ACTIVE", "type": "custom", "limit_by_accounts": true, "accounts": [ { "id": "bbd80931-6ae1-464c-9ba9-2f4a4ec63abb", "name": "IoT Account" } ], "format": "x509", "certificate_type": "end_entity" } ] } } } } } }, "post": { "tags": [ "Certificate templates" ], "operationId": "createCertificateTemplate", "summary": "Create certificate template", "description": "Use this endpoint to create a new end-entity or intermediate CA certificate template.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createCertificateTemplateRequest" } } } }, "responses": { "201": { "description": "Object with certificate template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateTemplateResponse" } } } } } } }, "/v1/certificate-template/{certificate_template_id}": { "get": { "tags": [ "Certificate templates" ], "summary": "Get certificate template details", "description": "Use this endpoint to get information about a certificate template with the given ID.\n", "operationId": "getCertificateTemplate", "parameters": [ { "in": "path", "name": "certificate_template_id", "required": true, "description": "Certificate template ID.", "schema": { "type": "string", "example": "2432c889-c2fc-4353-909a-a0ae1705451f" } } ], "responses": { "200": { "description": "Object with certificate template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateTemplateResponse" }, "example": { "id": "5eda32f3-26e3-4c94-8826-4da221e0d7e8", "name": "Client Auth Example", "created_at": "2022-06-09T11:04:29Z", "body": { "key_types": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ], "issue_types": [ "client_authentication", "server_authentication" ], "signature_algorithm": { "allowed_algorithms": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA", "match_issuer" ], "default_algorithm": "match_issuer" }, "subject": { "attributes": [ { "type": "common_name", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "organization_name", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "organization_unit", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "street_address", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "postal_code", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "locality", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "state", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "country", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "email", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] } ] }, "extensions": { "key_usage": { "critical": true, "allow_critical_override": true, "required_usages": { "rsa": [ "digital_signature", "non_repudiation", "key_encipherment", "data_encipherment" ], "ecdsa": [ "digital_signature", "non_repudiation", "key_agreement" ] }, "optional_usages": { "rsa": [ "digital_signature", "non_repudiation", "key_encipherment", "data_encipherment" ], "ecdsa": [ "digital_signature", "non_repudiation", "key_agreement" ] } }, "extended_key_usage": { "critical": true, "allow_critical_override": true, "include": "optional", "required_usages": [ { "oid": "client_authentication", "name": "" } ], "optional_usages": [ { "oid": "server_authentication", "name": "" }, { "oid": "code_signing", "name": "" }, { "oid": "email_protection", "name": "" }, { "oid": "smart_card_logon", "name": "" } ] }, "san": { "critical": false, "dns_name": { "include": "no", "auto_include_cn": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, "user_principal_name": { "include": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, "email": { "include": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] } } }, "renewal_settings": { "renew_valid_cert": "anytime", "renew_expired_cert": "anytime", "renew_revoked_cert": true, "renewal_key_pair": "optional", "allow_override_renewal_key_pair": true }, "serial_number_size": 20, "validity": { "min_duration": { "value": 10, "unit": "DAYS" }, "max_duration": { "value": 5, "unit": "YEARS" }, "default_duration": { "min": { "value": 10, "unit": "DAYS" }, "max": { "value": 5, "unit": "YEARS" } } } }, "status": "ACTIVE", "type": "custom", "limit_by_accounts": true, "accounts": [ { "id": "bbd80931-6ae1-464c-9ba9-2f4a4ec63abb", "name": "IoT Account" } ], "format": "x509", "certificate_type": "end_entity" } } } } } }, "put": { "tags": [ "Certificate templates" ], "summary": "Update certificate template", "operationId": "updateCertificateTemplate", "description": "Use this endpoint to update a certificate template.\n", "parameters": [ { "in": "path", "name": "certificate_template_id", "required": true, "description": "Certificate template ID.", "schema": { "type": "string", "example": "2432c889-c2fc-4353-909a-a0ae1705451f" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createCertificateTemplateRequest" } } } }, "responses": { "200": { "description": "Object with certificate template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateTemplateResponse" } } } } } } }, "/v1/certificate-template/{certificate_template_id}/clone": { "post": { "tags": [ "Certificate templates" ], "summary": "Clone certificate template", "description": "Use this endpoint to clone an existing certificate template.\n", "parameters": [ { "in": "path", "name": "certificate_template_id", "required": true, "description": "Certificate template ID.", "schema": { "type": "string", "example": "2432c889-c2fc-4353-909a-a0ae1705451f" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Unique name for the cloned certificate template.", "example": "Example template" }, "accounts": { "type": "array", "description": "List of account IDs for accounts that can use the template. The `accounts` array is required when cloning a `system` certificate template, as system templates have no account limitations by default. The `accounts` array is optional when cloning a `custom` certificate template, and if not provided, the cloned template uses the same account limitations that apply to the original certificate template.\n", "items": { "type": "string", "description": "Account ID.", "example": "3e4bbb55-f55a-4af7-92f5-ac35580dcfd4" } } } } } } }, "responses": { "201": { "description": "Object with certificate template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateTemplateResponse" } } } } } } }, "/v1/certificate-template/{certificate_template_id}/disable": { "put": { "tags": [ "Certificate templates" ], "summary": "Disable certificate template", "operationId": "disableCertificateTemplate", "description": "Use this endpoint to disable a certificate template. Disabled templates cannot be used to create new certificate profiles, but existing certificate profiles that use a disabled template will continue to work.\n", "parameters": [ { "in": "path", "name": "certificate_template_id", "required": true, "description": "Certificate template ID.", "schema": { "type": "string", "example": "2432c889-c2fc-4353-909a-a0ae1705451f" } } ], "responses": { "204": { "description": "Template disabled. No content.\n" } } } }, "/v1/certificate-template/{certificate_template_id}/enable": { "put": { "tags": [ "Certificate templates" ], "summary": "Enable certificate template", "operationId": "enableCertificateTemplate", "description": "Use this endpoint to enable a certificate template.\n", "parameters": [ { "in": "path", "name": "certificate_template_id", "required": true, "description": "Certificate template ID.", "schema": { "type": "string", "example": "2432c889-c2fc-4353-909a-a0ae1705451f" } } ], "responses": { "204": { "description": "Template enabled. No content.\n" } } } }, "/v1/certificate-template/{certificate_template_id}/delete": { "put": { "tags": [ "Certificate templates" ], "summary": "Delete certificate template", "operationId": "deleteCertificateTemplate", "description": "Use this endpoint to delete a certificate template. Deleted templates cannot be used to create new certificate profiles, but existing profiles that use a deleted template still work.\n\nAdditionally, deleted templates do not appear in search results on the **List certificate templates** endpoint with the default `status` filter. To search for deleted templates, use the query parameter `status=DELETED`.\n", "parameters": [ { "in": "path", "name": "certificate_template_id", "required": true, "description": "Certificate template ID.", "schema": { "type": "string", "example": "2432c889-c2fc-4353-909a-a0ae1705451f" } } ], "responses": { "204": { "description": "Template deleted. No content.\n" } } } }, "/v1/certificate-template/{certificate_template_id}/undelete": { "put": { "tags": [ "Certificate templates" ], "summary": "Restore certificate template", "operationId": "restoreCertificateTemplate", "description": "Use this endpoint to restore a deleted certificate template.\n", "parameters": [ { "in": "path", "name": "certificate_template_id", "required": true, "description": "Certificate template ID.", "schema": { "type": "string", "example": "2432c889-c2fc-4353-909a-a0ae1705451f" } } ], "responses": { "204": { "description": "Template restored. No content.\n" } } } }, "/v1/certificate-profile": { "get": { "tags": [ "Certificate profiles" ], "summary": "List certificate profiles", "description": "Use this endpoint to get a list of certificate profiles, or to search for profiles that meet the given criteria.\n", "operationId": "listCertificateProfiles", "parameters": [ { "in": "query", "name": "name", "description": "Limits results to certificate profiles with a name that contains the given string.\n", "schema": { "type": "string", "example": "Certificate profile name" } }, { "in": "query", "name": "account_id", "description": "Limits results to certificate profiles assigned to an account ID that is an exact match for the given ID.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "division_id", "description": "Limits results to certificate profiles assigned to a division ID that is an exact match for the given ID.", "schema": { "$ref": "#/components/schemas/division_id" } }, { "in": "query", "name": "template_name", "description": "Limits results to certificate profiles that use the given certificate template.", "schema": { "type": "string", "example": "Certificate template example" } }, { "in": "query", "name": "status", "description": "Limits results to certificate profiles with the given status. By default, deleted profiles do not appear in the results. To search for deleted profiles, use `status=DELETED`.\n", "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] } }, { "in": "query", "name": "created_from", "description": "Limits results to certificate profiles created after the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to certificate profiles created before the given date. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. Default `sort_by` property is `created_at`.\n", "schema": { "type": "string" } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive. Default `sort_direction` value is `DESC`.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 1000, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of certificate profiles that meet the search criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/certificateProfileResponse" } } } }, "example": { "limit": 20, "offset": 0, "pagination": true, "next": false, "total": 1, "records": [ { "id": "1fb93940-7580-4f94-a8ca-57585f9ecb2e", "name": "Certificate profile example", "account_id": "5220789d-df09-485f-aa21-d2979188b3ca", "certificate_template": { "id": "c376def4-b39a-4301-8391-6ffecd071057", "name": "Certificate template example" }, "allow_bare_public_key": false, "created_at": "2022-07-06T08:22:25Z", "status": "ACTIVE", "body": [ { "key": "certificate_value", "optional": false, "sources": [ "fixed_value" ], "value": "auto", "enabled": true }, { "key": "unique_certificate_value", "optional": false, "sources": [ "fixed_value" ], "value": "no", "enabled": true }, { "key": "signature_algorithm", "optional": false, "sources": [ "fixed_value" ], "value": "match_issuer", "enabled": true }, { "key": "allow_any_key_type", "optional": false, "sources": [ "fixed_value" ], "value": "yes", "enabled": true }, { "key": "allowed_key_types", "optional": false, "sources": [ "fixed_value" ], "value": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ], "enabled": true }, { "key": "subject.common_name", "optional": false, "sources": [ "user_supplied", "csr" ], "enabled": true }, { "key": "subject.organization_name", "optional": true, "sources": [ "user_supplied", "csr" ], "enabled": true }, { "key": "subject.organization_unit", "optional": true, "sources": [], "enabled": false }, { "key": "subject.street_address", "optional": true, "sources": [], "enabled": false }, { "key": "subject.postal_code", "optional": true, "sources": [], "enabled": false }, { "key": "subject.locality", "optional": true, "sources": [], "enabled": false }, { "key": "subject.state", "optional": true, "sources": [], "enabled": false }, { "key": "subject.country", "optional": true, "sources": [], "enabled": false }, { "key": "subject.unique_identifier", "optional": true, "sources": [ "user_supplied", "csr" ], "enabled": true }, { "key": "validity.duration_unit", "optional": false, "sources": [ "fixed_value" ], "value": "months", "enabled": true }, { "key": "validity.duration_value", "optional": false, "sources": [ "fixed_value" ], "value": 9, "enabled": true }, { "key": "key_usage.critical", "optional": true, "sources": [ "fixed_value" ], "value": "yes", "enabled": false }, { "key": "extended_key_usage.critical", "optional": true, "sources": [ "fixed_value" ], "value": "yes", "enabled": false }, { "key": "extended_key_usage.additional_values", "optional": true, "sources": [], "enabled": false }, { "key": "renewal_settings.renew_valid_cert", "optional": false, "sources": [ "fixed_value" ], "value": "anytime", "enabled": true }, { "key": "renewal_settings.renew_expired_cert", "optional": false, "sources": [ "fixed_value" ], "value": "anytime", "enabled": true }, { "key": "renewal_settings.renew_revoked_cert", "optional": false, "sources": [ "fixed_value" ], "value": true, "enabled": true }, { "key": "renewal_settings.renewal_key_pair", "optional": false, "sources": [ "fixed_value" ], "value": "optional", "enabled": true } ], "enrollment_methods": [], "certificate_format": "x509", "certificate_type": "end_entity", "ca_connector_type": "digicert_one", "divisions": [ { "id": "4340c299-f39c-4fcf-8d3a-650d24e5eb99", "name": "Example division" } ] } ] } } } } } }, "post": { "tags": [ "Certificate profiles" ], "summary": "Create certificate profile", "description": "Use this endpoint to create a certificate profile.\n", "operationId": "createCertificateProfile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createCertificateProfileRequest" } } } }, "responses": { "201": { "description": "Object with certificate profile details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateProfileResponse" } } } } } } }, "/v1/certificate-profile/{certificate_profile_id}": { "get": { "tags": [ "Certificate profiles" ], "operationId": "getCertificateProfile", "summary": "Get certificate profile", "description": "Use this endpoint to get a certificate profile.\n", "parameters": [ { "in": "path", "name": "certificate_profile_id", "description": "Certificate profile ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9131f8f6-acdc-4ec2-a149-489c8ef58519" } } ], "responses": { "200": { "description": "Object with certificate profile details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateProfileResponse" } } } } } }, "put": { "tags": [ "Certificate profiles" ], "summary": "Update certificate profile", "operationId": "updateCertificateProfile", "description": "Use this endpoint to update a certificate profile.\n", "parameters": [ { "in": "path", "name": "certificate_profile_id", "description": "Certificate profile ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9131f8f6-acdc-4ec2-a149-489c8ef58519" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateCertificateProfileRequest" } } } }, "responses": { "200": { "description": "Object with certificate profile details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateProfileResponse" } } } } } } }, "/v1/certificate-profile/{certificate_profile_id}/disable": { "put": { "tags": [ "Certificate profiles" ], "summary": "Disable certificate profile", "operationId": "disableCertificateProfile", "description": "Use this endpoint to disable a certificate profile. Disabled certificate profiles cannot be used to create new enrollment profiles, but existing enrollment profiles that use a disabled certificate profile will continue to work.\n", "parameters": [ { "in": "path", "name": "certificate_profile_id", "description": "Certificate profile ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9131f8f6-acdc-4ec2-a149-489c8ef58519" } } ], "responses": { "204": { "description": "Profile disabled. No content." } } } }, "/v1/certificate-profile/{certificate_profile_id}/enable": { "put": { "tags": [ "Certificate profiles" ], "summary": "Enable certificate profile", "operationId": "enableCertificateProfile", "description": "Use this endpoint to enable a disabled certificate profile.\n", "parameters": [ { "in": "path", "name": "certificate_profile_id", "description": "Certificate profile ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9131f8f6-acdc-4ec2-a149-489c8ef58519" } } ], "responses": { "204": { "description": "Profile enabled. No content." } } } }, "/v1/certificate-profile/{certificate_profile_id}/delete": { "put": { "tags": [ "Certificate profiles" ], "summary": "Delete certificate profile", "operationId": "deleteCertificateProfile", "description": "Use this endpoint to delete a certificate profile. Deleted certificate profiles cannot be used to create new enrollment profiles, but existing enrollment profiles that use a deleted certificate profile will continue to work.\n\nAdditionally, deleted certificate profiles do not appear in search results on the **List certificate profiles** endpoint with the default `status` filter. To search for deleted certificate profiles, use the query parameter `status=DELETED`.\n", "parameters": [ { "in": "path", "name": "certificate_profile_id", "description": "Certificate profile ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9131f8f6-acdc-4ec2-a149-489c8ef58519" } } ], "responses": { "204": { "description": "Profile deleted. No content." } } } }, "/v1/certificate-profile/{certificate_profile_id}/undelete": { "put": { "tags": [ "Certificate profiles" ], "summary": "Restore certificate profile", "operationId": "restoreCertificateProfile", "description": "Use this endpoint to restore a deleted certificate profile.\n", "parameters": [ { "in": "path", "name": "certificate_profile_id", "description": "Certificate profile ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9131f8f6-acdc-4ec2-a149-489c8ef58519" } } ], "responses": { "204": { "description": "Profile restored. No content." } } } }, "/v1/certificate-profile/{certificate_profile_id}/division/assign": { "put": { "tags": [ "Certificate profiles" ], "summary": "Assign divisions to certificate profile", "operationId": "assignCertificateProfileDivisions", "description": "Use this endpoint to assign divisions to a certificate profile. Division IDs are sourced from the [List divisions](#/Divisions/listDivisions) API endpoint.\n", "parameters": [ { "in": "path", "name": "certificate_profile_id", "description": "Certificate profile ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9131f8f6-acdc-4ec2-a149-489c8ef58519" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "List of one or more divisions to assign to the certificate profile.", "items": { "$ref": "#/components/schemas/division_id" } } } } }, "responses": { "204": { "description": "Divisions assigned. No content." } } } }, "/v1/certificate-profile/{certificate_profile_id}/division/unassign": { "put": { "tags": [ "Certificate profiles" ], "summary": "Unassign divisions from certificate profile", "operationId": "unassignCertificateProfileDivisions", "description": "Use this endpoint to unassign divisions from a certificate profile. Division IDs are sourced from the [List divisions](#/Divisions/listDivisions) API endpoint.\n", "parameters": [ { "in": "path", "name": "certificate_profile_id", "description": "Certificate profile ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9131f8f6-acdc-4ec2-a149-489c8ef58519" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "List of one or more divisions to unassign from the certificate profile.", "items": { "$ref": "#/components/schemas/division_id" } } } } }, "responses": { "204": { "description": "Divisions unassigned. No content." } } } }, "/v1/gateway/{gateway_id}": { "get": { "tags": [ "Gateways" ], "description": "Use this endpoint to get information about the gateway with the given ID.", "summary": "Get gateway details", "operationId": "getGatewayDetails", "parameters": [ { "in": "path", "required": true, "description": "Gateway ID.", "name": "gateway_id", "schema": { "type": "string", "format": "uuid", "example": "ab810ed0-799b-45e4-9b45-c9d33881ba78" } } ], "responses": { "200": { "description": "Gateway object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/gatewayResponse" } } } } } }, "put": { "tags": [ "Gateways" ], "description": "Use this endpoint to update the gateway with the given ID.\n\nSome updates change the gateway's configuration file. For these updates, you need to download the modified configuration file, apply it to the gateway host, and restart the gateway.\n\n- To check if an update changed the configuration file, submit a request to the [Get gateway details](#/Gateways/getGatewayDetails) endpoint. In the response, check the `config_updated_at` and `recent_config_was_downloaded` values.\n\n- To download the YAML configuration file for a gateway, use the [Download gateway configuration file](#/Gateways/downloadGatewayConfig) endpoint.\n", "operationId": "updateGateway", "summary": "Update gateway", "parameters": [ { "in": "path", "required": true, "description": "Gateway ID.", "name": "gateway_id", "schema": { "type": "string", "format": "uuid", "example": "ab810ed0-799b-45e4-9b45-c9d33881ba78" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/gatewayRequest" } } } }, "responses": { "200": { "description": "Gateway object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/gatewayResponse" } } } } } } }, "/v1/gateway": { "get": { "tags": [ "Gateways" ], "description": "Use this endpoint to get a list of records with information about your gateways.\n\nBy default, this endpoint only returns active and disabled gateways. To search for deleted gateways, append the query string `status=deleted` to the request URL. \n", "summary": "List gateways", "operationId": "listGateways", "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to gateways for an account with the given ID.", "schema": { "type": "string", "format": "uuid", "example": "92bbf15d-8d39-4525-ab77-84021532d4d2" } }, { "in": "query", "name": "name", "description": "Limits results to gateways with a `name` that contains the given string.", "schema": { "type": "string", "example": "Gateway name" } }, { "in": "query", "name": "ip_address", "description": "Limits results to gateways with IP address restrictions containing the given string.", "schema": { "type": "string", "example": "192.0.2.0" } }, { "in": "query", "name": "status", "description": "Limits results to gateways with the given status. If not provided, only active and disabled gateways are returned.", "schema": { "type": "string", "example": "deleted" } }, { "in": "query", "name": "created_at_from", "description": "Limits results to gateways created **after** the given date and time (UTC). Use with `created_at_to` to search for gateways with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "created_at_to", "description": "Limits results to gateways created **before** the given date and time (UTC). Use with `created_at_from` to search for gateways with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "config_status", "description": "Limits results to gateways with the given `config_status`.", "schema": { "type": "string", "enum": [ "in_progress", "completed" ], "example": "in_progress" } }, { "in": "query", "name": "mac_address", "description": "Limits results to gateways hosted on servers with MAC addresses that contain the given string.", "schema": { "type": "string", "example": "gg-hh-ii-kk-ll-mm" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "type": "string", "enum": [ "name", "mac_address", "status", "created_at", "config_updated_at", "config_downloaded_at", "recent_config_was_downloaded" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 1000, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of gateways.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of gateway records.", "items": { "$ref": "#/components/schemas/gatewayResponse" } } } } } } } } }, "post": { "tags": [ "Gateways" ], "summary": "Create gateway", "operationId": "createGateway", "description": "Use this endpoint to create a gateway. A gateway is an application installed on a host server that can connect to DigiCert® IoT Trust Manager. Devices without internet connectivity can send requests to the gateway, and the gateway routes those requests to DigiCert® IoT Trust Manager.\n\nAfter creating a gateway, DigiCert® IoT Trust Manager generates a YAML configuration file with comments describing how to finish setting up the gateway on your host server. To download the YAML configuration file for a gateway, use the [Download gateway configuration file](#/Gateways/downloadGatewayConfig) endpoint.\n\nRequired parameters:\n\n- `account_id`\n\n- `name`\n\n- `use_authentication_api_token` or `use_authentication_certificate`\n\n- `server_user_email`\n\nOptional parameters:\n\n- `mac_address`\n\nConditionally required parameters:\n\n- Required if `http_enabled` is true: `http_port`\n\n- Required if `ssl_enabled` is true: `ssl_port`, `ssl_certificate_pkcs12_file_path`, `ssl_certificate_pkcs12_key_store_password`\n\n- Required if `use_authentication_api_token` is true: `authentication_api_token`\n\n- Required if `use_authentication_certificate` is true: `authentication_certificate_pkcs12`, `authentication_certificate_pkcs12_password`\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/gatewayCreateRequest" } } } }, "responses": { "200": { "description": "Gateway object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/gatewayResponse" } } } } } } }, "/v1/gateway/{gateway_id}/enable": { "put": { "tags": [ "Gateways" ], "summary": "Enable gateway", "description": "Use this endpoint to enable a gateway.\n", "operationId": "enableGateway", "parameters": [ { "in": "path", "required": true, "description": "Gateway ID.", "name": "gateway_id", "schema": { "type": "string", "format": "uuid", "example": "ab810ed0-799b-45e4-9b45-c9d33881ba78" } } ], "responses": { "204": { "description": "No content" } } } }, "/v1/gateway/{gateway_id}/disable": { "put": { "tags": [ "Gateways" ], "summary": "Disable gateway", "description": "Use this endpoint to disable a gateway.\n", "operationId": "disableGateway", "parameters": [ { "in": "path", "required": true, "description": "Gateway ID.", "name": "gateway_id", "schema": { "type": "string", "format": "uuid", "example": "ab810ed0-799b-45e4-9b45-c9d33881ba78" } } ], "responses": { "204": { "description": "No content" } } } }, "/v1/gateway/{gateway_id}/delete": { "put": { "tags": [ "Gateways" ], "summary": "Delete gateway", "description": "Use this endpoint to delete a gateway.\n", "operationId": "deleteGateway", "parameters": [ { "in": "path", "required": true, "description": "Gateway ID.", "name": "gateway_id", "schema": { "type": "string", "format": "uuid", "example": "ab810ed0-799b-45e4-9b45-c9d33881ba78" } } ], "responses": { "204": { "description": "No content" } } } }, "/v1/ocsp-group": { "get": { "summary": "List OCSP groups", "operationId": "listOCSPGroups", "description": "Use this endpoint to list OCSP groups in DigiCert® IoT Trust Manager.\n\nBy default, returns all OCSP groups for each account the authenticated client belongs to. Results are sorted in descending order by `created_at` date. To search for a specific OCSP group or change the pagination settings, use query string parameters.\n", "tags": [ "OCSP groups" ], "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to OCSP groups belonging to the account with the given ID.", "schema": { "type": "string", "format": "uuid", "example": "92bbf15d-8d39-4525-ab77-84021532d4d2" } }, { "in": "query", "name": "division_id", "description": "Limits results to OCSP groups for the division with the given ID.", "schema": { "type": "string", "format": "uuid", "example": "ac27bde9-b7ff-4b25-805d-854ac7da2614" } }, { "in": "query", "name": "name", "description": "Limits results to OCSP groups with a `name` that contains the given string.", "schema": { "type": "string", "example": "Example OCSP group" } }, { "in": "query", "name": "status", "description": "Limits results to OCSP groups with the given status.", "schema": { "type": "string", "enum": [ "ACTIVE" ] } }, { "in": "query", "name": "certificate_common_name", "description": "Limits results to OCSP groups that include certificates with a common name containing the given string.", "schema": { "type": "string", "example": "Device 001" } }, { "in": "query", "name": "certificate_serial_number", "description": "Limits results to the OCSP group that includes the certificate with the given serial number.", "schema": { "type": "string", "example": "3031D3B7E49697B5BFF95F972E8C917D5A2BDE4D" } }, { "in": "query", "name": "issuer_common_name", "description": "Limits results to OCSP groups for issuing CAs with a common name containing the given string.", "schema": { "type": "string", "example": "Issuing CA" } }, { "in": "query", "name": "issuer_serial_number", "description": "Limits results to OCSP groups for the issuing CA with the given serial number.", "schema": { "type": "string", "example": "1234D1B7345647B5B6F95F572E8C917D5A123456" } }, { "in": "query", "name": "device_identifier", "description": "Limits results to OCSP groups for certificates with a device name that contains the given string.", "schema": { "type": "string", "example": "Device name" } }, { "in": "query", "name": "certificate_profile_id", "description": "Limits results to OCSP groups for certificates issued from the certificate profile with the given ID (UUID).", "schema": { "type": "string", "format": "uuid", "example": "93816fc2-f62e-4dbf-8f39-8db1137c6f31" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to OCSP groups for certificates issued from the enrollment profile with the given ID (UUID).", "schema": { "type": "string", "example": "2953d4a7-883b-4b6c-a865-f78f1bc64490", "format": "uuid" } }, { "in": "query", "name": "created_at_from", "description": "Limits results to OCSP groups created **after** the given date and time (UTC). Use with `created_at_to` to search for OCSP groups with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "created_at_to", "description": "Limits results to OCSP groups created **before** the given date and time (UTC). Use with `created_at_from` to search for OCSP groups with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "type": "string", "enum": [ "id", "division_id", "name", "status", "ica_id", "ica_name", "created_at" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Default is descending (`DESC`). Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of OCSP group objects.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "Array of OCSP group records.\n", "uniqueItems": true, "items": { "$ref": "#/components/schemas/OCSPGroupResponse" } } } } } } } } }, "post": { "summary": "Create OCSP group", "operationId": "createOCSPGroup", "description": "Use this endpoint to create an OCSP group for certificates in DigiCert® IoT Trust Manager.\n\nWith OCSP groups, you can get the status of every certificate in the group by making a single OCSP request for any certificate in the group.\n\nWhen creating an OCSP group, keep the following in mind:\n\n- All certificates in an OCSP group must be issued through both the same division and root or intermediate CA.\n\n- A certificate can only be assigned to one OCSP group.\n\n- The issuing CA for certificates in the group must be configured to include OCSP.\n", "tags": [ "OCSP groups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCSPGroupRequest" } } } }, "responses": { "201": { "description": "OCSP group details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCSPGroupResponse" } } } } } } }, "/v1/ocsp-group/{ocsp_group_id}": { "get": { "summary": "Get OCSP group details", "operationId": "getOCSPGroupDetails", "description": "Use this endpoint to get details about the given OCSP group.\n", "tags": [ "OCSP groups" ], "parameters": [ { "$ref": "#/components/parameters/ocsp_group_id" } ], "responses": { "200": { "description": "OCSP group objects.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCSPGroupResponse" } } } } } }, "put": { "summary": "Update OCSP group name", "operationId": "updateOCSPGroup", "tags": [ "OCSP groups" ], "description": "Use this endpoint to update the name of an OCSP group.\n", "parameters": [ { "$ref": "#/components/parameters/ocsp_group_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "OCSP group name. Must be unique within the account. Character limit: 64\n", "maxLength": 64, "example": "Updated OCSP group" } } } } } }, "responses": { "200": { "description": "OCSP group objects.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCSPGroupResponse" } } } } } }, "delete": { "summary": "Delete OCSP group", "operationId": "deleteOCSPGroup", "tags": [ "OCSP groups" ], "description": "Use this endpoint to delete an OCSP group.\n\n**Warning!** This is a destructive operation. Deleting an OCSP group removes all certificates from the OCSP group. Deleted OCSP groups cannot be restored.\n", "parameters": [ { "$ref": "#/components/parameters/ocsp_group_id" } ], "responses": { "204": { "description": "No content.\n" } } } }, "/v1/ocsp-group/{ocsp_group_id}/add-certificates": { "put": { "summary": "Add certificates to OCSP group", "operationId": "addCertsOCSPGroup", "description": "Use this endpoint to add certificates to an OCSP group.\n\nWhen adding certificates to an OCSP group, keep the following in mind:\n\n- All certificates must be issued through the OCSP group's division (`division_id`) and issuing CA (`ica_id`).\n\n- Certificates already in an OCSP group cannot be added to another OCSP group.\n", "tags": [ "OCSP groups" ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "List of IDs for certificates to add to the OCSP group.\n\nRequirements:\n\n- All certificates must be issued through the OCSP group's division (`division_id`) and issuing CA (`ica_id`).\n\n- Certificates already in an OCSP group cannot be added to another OCSP group.\n", "minItems": 1, "example": [ "81133e8f-6b0d-4bf1-ac9e-402e72e006b0", "6ef9246f-e071-4a8e-a871-0ea4314cde64", "5be444dd-ea46-4cac-9e15-823d16012c69" ], "items": { "type": "string", "format": "uuid", "description": "Certificate ID (UUID).", "example": "146c88ae-8db9-4186-9a4a-dcfd267b67dd" } } } } }, "responses": { "204": { "description": "No content." } } } }, "/v1/ocsp-group/{ocsp_group_id}/remove-certificates": { "put": { "summary": "Remove certificates from OCSP group", "operationId": "removeCertsOCSPGroup", "description": "Use this endpoint to remove certificates from an OCSP group.\n", "tags": [ "OCSP groups" ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "List of IDs for certificates to remove from the OCSP group. Certificates not present in the OCSP group are ignored.\n", "minItems": 1, "example": [ "81133e8f-6b0d-4bf1-ac9e-402e72e006b0", "6ef9246f-e071-4a8e-a871-0ea4314cde64", "5be444dd-ea46-4cac-9e15-823d16012c69" ], "items": { "type": "string", "format": "uuid", "description": "Certificate ID (UUID).", "example": "146c88ae-8db9-4186-9a4a-dcfd267b67dd" } } } } }, "responses": { "204": { "description": "No content." } } } }, "/v1/ocsp-group/{ocsp_group_id}/certificates": { "get": { "summary": "List certificates in OCSP group", "operationId": "listOCSPGroupCerts", "description": "Use this endpoint to list certificates in the given OCSP group.\n\nBy default, returns all certificates that belong to the given OCSP group. Results are sorted in descending order by `created` date. To search for a specific certificate or change the pagination settings, use query string parameters.\n", "tags": [ "OCSP groups" ], "parameters": [ { "$ref": "#/components/parameters/ocsp_group_id" }, { "in": "query", "name": "account_id", "description": "Limits results to certificates with an account ID that is an exact match for the given string.", "schema": { "$ref": "#/components/schemas/account_id" } }, { "in": "query", "name": "division_id", "description": "Limits results to certificates with a division ID that is an exact match for the given string.", "schema": { "type": "string", "format": "uuid", "example": "135fd0f0-62c8-4a89-b8ca-416ae7be2ce3" } }, { "in": "query", "name": "status", "description": "Limits results to certificates with the given status.", "schema": { "type": "string", "example": "ISSUED", "enum": [ "ISSUED", "EXPIRED", "REVOKED" ] } }, { "in": "query", "name": "serial_number", "description": "Limits results to certificates with a serial number that contains the given string.\n", "schema": { "$ref": "#/components/schemas/certificate_serial_number" } }, { "in": "query", "name": "common_name", "description": "Limits results to certificates with a common name that contains the given string.\n", "schema": { "type": "string", "example": "Example common name" } }, { "in": "query", "name": "certificate_value", "description": "Limits results to certificates with a certificate value that contains the given string.", "schema": { "example": "Certificate value", "type": "string" } }, { "in": "query", "name": "device_identifier", "description": "Limits results to certificates with a device name (`device_identifier`) that contains the given string.", "schema": { "example": "Device name", "type": "string" } }, { "in": "query", "name": "device_id", "description": "Limits results to certificates with a device ID that is an exact match for the given string.", "schema": { "example": "b85f78a0-b083-46f3-bc71-92e892a81a45", "type": "string" } }, { "in": "query", "name": "enrollment_method", "description": "Limits results to certificates issued using the given enrollment method.\n", "schema": { "type": "string", "example": "API", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH" ] } }, { "in": "query", "name": "enrollment_method", "description": "Limits results to certificates issued using the given enrollment method.\n", "schema": { "type": "string", "example": "API", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH" ] } }, { "in": "query", "name": "created_from", "description": "Limits results to certificates created after the given date. UTC timezone. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "created_to", "description": "Limits results to certificates created before the given date. UTC timezone. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "valid_to_start", "description": "Limits results to certificates with a `valid_to` value on or after the given date or date-time. Use with `valid_to_end` to search for certificates with a `valid_to` date in a specific range. UTC timezone. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "format": "date-time", "example": "2021-04-22", "type": "string" } }, { "in": "query", "name": "valid_to_end", "description": "Limits results to certificates with a `valid_to` value on or before the given date or date-time. Use with `valid_to_start` to search for certificates with a `valid_to` date in a specific range. UTC timezone. Format: `YYYY-MM-DD` or `YYYY-MM-dDTHH:mm:ssZ`.\n", "schema": { "format": "date-time", "type": "string", "example": "2021-04-22" } }, { "in": "query", "name": "issuer_common_name", "description": "Limits results to certificates issued from a CA with a common name that contains the given string.\n", "schema": { "type": "string", "example": "Issuer common name" } }, { "in": "query", "name": "issuer_serial_number", "description": "Limits results to certificates issued from the CA with a serial number that is an exact match for the given string.\n", "schema": { "type": "string", "example": "1234D1B7345647B5B6F95F572E8C917D5A123456" } }, { "in": "query", "name": "key_type", "description": "Limits results to certificates with key type that contains the given string.\n", "schema": { "type": "string", "example": "RSA" } }, { "in": "query", "name": "enrollment_profile_id", "description": "Limits results to certificates issued using an enrollment profile with an ID that is an exact match for the given string.\n", "schema": { "type": "string", "example": "IOT_07ccbdc1-35d9-6ba2-7d3b-197b2c456088" } }, { "in": "query", "name": "revoked_from", "description": "Limits results to certificates revoked after a specific date. UTC timezone. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "revoked_to", "description": "Limits results to certificates revoked before a specific date. UTC timezone. Format: `YYYY-MM-DD`\n", "schema": { "type": "string", "format": "date-time", "example": "2020-06-30" } }, { "in": "query", "name": "device_id", "description": "Limits results to certificates with a device ID that is an exact match for the given string.\n", "schema": { "type": "string", "format": "uuid", "example": "a22b9829-361f-4a9d-a402-714d5521fae4" } }, { "in": "query", "name": "certificate_type", "description": "Limits results to certificates of the given type.\n", "schema": { "type": "string", "example": "x509", "enum": [ "x509", "global-platform", "attribute-certificate" ] } }, { "in": "query", "name": "created_in_last_n_days", "description": "Limits results to certificates created in the last *n* days, where *n* is a numerical value you provide in your request.\n", "schema": { "type": "number", "example": 20 } }, { "in": "query", "name": "created_in_current_month", "description": "If true, limits results to certificates created in the current month.\n", "schema": { "type": "boolean", "example": true, "default": false } }, { "in": "query", "name": "created_in_previous_month", "description": "If true, limits results to certificates created in the previous month.\n", "schema": { "type": "boolean", "example": true, "default": false } }, { "in": "query", "name": "expiring_in_next_n_days", "description": "Limits results to certificates expiring in the next *n* days, where *n* is a numerical value you provide in your request.\n", "schema": { "type": "number", "example": 20 } }, { "in": "query", "name": "expiring_in_remaining_of_current_month", "description": "If true, limits results to certificates expiring before the end of the current month.\n", "schema": { "type": "number", "example": 20 } }, { "in": "query", "name": "expiring_in_next_month", "description": "If true, limits results to certificates expiring before the end of the next month.\n", "schema": { "type": "number", "example": 20 } }, { "in": "query", "name": "key_usage", "description": "Limits results to certificates with the given key usage extension.\n", "schema": { "type": "string", "example": "digital_signature" } }, { "in": "query", "name": "extended_key_usage", "description": "Limits results to certificates with the given extended key usage (EKU) extension.\n", "schema": { "type": "string", "example": "client_authentication" } }, { "in": "query", "name": "certificate_policies", "description": "Limits results to certificates with the given certificate policies.\n", "schema": { "type": "string", "example": "" } }, { "in": "query", "name": "authentication_id", "description": "Limits results to certificates requested with an authentication ID that contains the given string.\n", "schema": { "type": "string", "example": "20a96dd7-3a14-4e5d-8949-c869b24997cd" } }, { "in": "query", "name": "authentication_type", "description": "Limits results to certificates requested with the given authentication type.\n", "schema": { "type": "string", "example": "user", "enum": [ "user", "passcode", "certificate", "authentication_ca", "authentication_certificate" ] } }, { "in": "query", "name": "authentication_name", "description": "Limits results to certificates requested with an authentication name that contains the given string.\n", "schema": { "type": "string", "example": "local.admin" } }, { "in": "query", "name": "ca_connector_type", "description": "Limits results to certificates with the given CA connector type.\n", "schema": { "type": "string", "enum": [ "digicert_one", "digicert_cis" ] } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. If not provided, results are sorted in descending order by date created (`created_at`).\n", "schema": { "type": "string", "enum": [ "created_at", "certificate_value", "valid_from", "valid_to" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20, "example": 1 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "description": "List of certificates in the OCSP group.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "List of certificates.", "items": { "$ref": "#/components/schemas/certificateDetails" } } } } } } } } } }, "/v1/trust-bundle": { "get": { "summary": "List trust bundles", "operationId": "listTrustBundles", "description": "Use this endpoint to list trust bundles in DigiCert® IoT Trust Manager.\n\nBy default, returns all trust bundles for each account the authenticated client belongs to. Results are sorted in descending order by `created_at` date. To search for a specific trust bundle or change the pagination settings, use query string parameters.\n", "tags": [ "Trust bundles" ], "parameters": [ { "in": "query", "name": "account_id", "description": "Limits results to trust bundles belonging to the account with the given ID.", "schema": { "type": "string", "format": "uuid", "example": "92bbf15d-8d39-4525-ab77-84021532d4d2" } }, { "in": "query", "name": "name", "description": "Limits results to trust bundles with a `name` that contains the given string.", "schema": { "type": "string", "example": "Example Trust Bundle" } }, { "in": "query", "name": "status", "description": "Limits results to trust bundles with the given status.", "schema": { "type": "string", "enum": [ "ACTIVE" ] } }, { "in": "query", "name": "certificate_common_name", "description": "Limits results to trust bundles that includes certificates with a common name containing the given string.", "schema": { "type": "string", "example": "Certificate 001" } }, { "in": "query", "name": "certificate_serial_number", "description": "Limits results to trust bundles that includes the certificate with the given serial number.", "schema": { "type": "string", "example": "3031D3B7E49697B5BFF95F972E8C917D5A2BDE4D" } }, { "in": "query", "name": "created_at_from", "description": "Limits results to trust bundles created **after** the given date and time (UTC). Use with `created_at_to` to search for trust bundles with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "created_at_to", "description": "Limits results to trust bundles created **before** the given date and time (UTC). Use with `created_at_from` to search for trust bundles with a `created_at` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "type": "string", "enum": [ "id", "name", "status", "created_at", "updated_at" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Default is descending (`DESC`). Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of trust bundle objects.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "Array of trust bundle records.\n", "uniqueItems": true, "items": { "$ref": "#/components/schemas/TrustBundleResponse" } } } } } } } } }, "post": { "summary": "Create trust bundle", "operationId": "createTrustBundle", "description": "Use this endpoint to create a trust bundle for certificates in DigiCert® IoT Trust Manager.\n", "tags": [ "Trust bundles" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleCreateRequest" } } } }, "responses": { "201": { "description": "OCSP group details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleResponse" } } } } } } }, "/v1/trust-bundle/{trust_bundle_id}": { "get": { "summary": "Get trust bundle details", "operationId": "getTrustBundleDetails", "description": "Use this endpoint to get details about the given trust bundle.\n", "tags": [ "Trust bundles" ], "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "responses": { "200": { "description": "Trust bundle object.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleResponse" } } } } } }, "put": { "summary": "Update trust bundle", "operationId": "updateTrustBundle", "tags": [ "Trust bundles" ], "description": "Use this endpoint to update trust bundle.\n", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleUpdateRequest" } } } }, "responses": { "200": { "description": "Trust bundle object.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleResponse" } } } } } } }, "/v1/trust-bundle/{trust_bundle_id}/disable": { "put": { "tags": [ "Trust bundles" ], "summary": "Disable trust bundle", "operationId": "disableTrustBundle", "description": "Use this endpoint to disable a trust bundle. Disabled trust bundles cannot be downloaded.\n", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "responses": { "204": { "description": "Trust bundle disabled. No content." } } } }, "/v1/trust-bundle/{trust_bundle_id}/enable": { "put": { "tags": [ "Trust bundles" ], "summary": "Enable trust bundle", "operationId": "enableTrustBundle", "description": "Use this endpoint to enable a trust bundle.\n", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "responses": { "204": { "description": "Trust bundle enabled. No content." } } } }, "/v1/trust-bundle/{trust_bundle_id}/delete": { "put": { "tags": [ "Trust bundles" ], "summary": "Delete trust bundle", "operationId": "deleteTrustBundle", "description": "Use this endpoint to delete a trust bundle. Deleted trust bundles cannot be downloaded.\n", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "responses": { "204": { "description": "Trust bundle deleted. No content." } } } }, "/v1/trust-bundle/{trust_bundle_id}/undelete": { "put": { "tags": [ "Trust bundles" ], "summary": "Undelete trust bundle", "operationId": "undeleteTrustBundle", "description": "Use this endpoint to undelete a trust bundle.\n", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "responses": { "204": { "description": "Trust bundle undeleted. No content." } } } }, "/v1/trust-bundle/{trust_bundle_id}/certificates": { "get": { "summary": "List trust bundle certificates", "operationId": "listTrustBundleCertificate", "description": "Use this endpoint to list certificates included into trust bundle in DigiCert® IoT Trust Manager.\n\nBy default, returns all certificates included into trust bundle. Results are sorted in descending order by `created_at` date. To search for a specific certificate or change the pagination settings, use query string parameters.\n", "tags": [ "Trust bundles" ], "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" }, { "in": "query", "name": "common_name", "description": "Limits results to certificates with a common name containing the given string.", "schema": { "type": "string", "example": "Certificate 001" } }, { "in": "query", "name": "serial_number", "description": "Limits results to certificates with a serial number containing the given string.", "schema": { "type": "string", "example": "1f632ae04d9237b628667d081e955d3e707c74ca" } }, { "in": "query", "name": "certificate_valid_from_from", "description": "Limits results to certificates valid after **after** the given date and time (UTC). Use with `certificate_valid_from_to` to search for certificates with a `certificate_valid_from` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "certificate_valid_from_to", "description": "Limits results to certificates valid **before** the given date and time (UTC). Use with `certificate_valid_from_from` to search for certificates with a `certificate_valid_from` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "certificate_valid_to_from", "description": "Limits results to certificates that expires after **after** the given date and time (UTC). Use with `certificate_valid_to_to` to search for certificate with a `certificate_valid_to` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "certificate_valid_to_to", "description": "Limits results to certificates that expires **before** the given date and time (UTC). Use with `certificate_valid_to_from` to search for certificates with a `certificate_valid_to` date in a specific range.\n", "schema": { "type": "string", "format": "date-time", "example": "yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive.\n", "schema": { "type": "string", "enum": [ "common_name", "serial_number", "certificate_valid_from", "certificate_valid_to" ] } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Default is descending (`DESC`). Case-insensitive.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of trust bundle objects.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "Array of certificates in trust bundle.\n", "uniqueItems": true, "items": { "$ref": "#/components/schemas/TrustBundleCertificateResponse" } } } } } } } } }, "post": { "summary": "Add certificates to trust bundle", "operationId": "addCertificatesToTrustBundle", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "description": "Use this endpoint to add certificates to trust bundle in DigiCert® IoT Trust Manager.\n", "tags": [ "Trust bundles" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleAddCertificatesRequest" } } } }, "responses": { "204": { "description": "Certificates added to trust bundle. No content." } } } }, "/v1/trust-bundle/{trust_bundle_id}/certificates/remove": { "put": { "summary": "Remove certificates from trust bundle", "operationId": "removeCertificatesFromTrustBundle", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "description": "Use this endpoint to remove certificates from trust bundle in DigiCert® IoT Trust Manager.\n", "tags": [ "Trust bundles" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleRemoveCertificatesRequest" } } } }, "responses": { "204": { "description": "Certificates removed from trust bundle. No content." } } } }, "/v1/trust-bundle/{trust_bundle_id}/download": { "get": { "summary": "Download trust bundle certificates", "operationId": "downloadTrustBundleCertificates", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" }, { "in": "query", "name": "format", "description": "Allow to select download format for certificates. If not provided then default format set in trust bundle will be used", "schema": { "type": "string", "example": "individual_crt", "enum": [ "individual_crt", "individual_pem", "individual_cer", "individual_der", "single_p7b", "single_pem" ] } } ], "description": "Use this endpoint to download trust bundle certificates in DigiCert® IoT Trust Manager.\n\nWhen trust bundle is disabled or deleted, or don't contains certificates error response will be returned\n", "tags": [ "Trust bundles" ], "responses": { "200": { "description": "Return trust bundle certificates in selected or defaul format." } } } }, "/v1/trust-bundle/{trust_bundle_id}/divisions": { "get": { "summary": "Get divisions assigned to trust bundle", "operationId": "getDivisionsAssignedToTrustBundle", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" }, { "in": "query", "name": "name", "description": "Division name filter", "schema": { "type": "string" } }, { "in": "query", "name": "sort_by", "description": "Sorts results by the given property. Case-insensitive. Default `sort_by` property is `created_at`.\n", "schema": { "type": "string" } }, { "in": "query", "name": "sort_direction", "description": "Sorts results in ascending or descending order by the value of the `sort_by` property. Case-insensitive. Default `sort_direction` value is `DESC`.\n", "schema": { "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "limit", "description": "Limits the number of records to include in the results.", "schema": { "type": "integer", "maximum": 100, "default": 20 } }, { "in": "query", "name": "offset", "description": "Index of the first record to include in the results.", "schema": { "type": "integer", "default": 0 } } ], "description": "Use this endpoint to get divisions assigned to trust bundle\n", "tags": [ "Trust bundles" ], "responses": { "200": { "description": "List of trust bundle objects.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/limit" }, "offset": { "$ref": "#/components/schemas/offset" }, "pagination": { "$ref": "#/components/schemas/pagination" }, "next": { "$ref": "#/components/schemas/next" }, "total": { "$ref": "#/components/schemas/total" }, "records": { "type": "array", "description": "Array of divisions assigned to trust bundle.\n", "uniqueItems": true, "items": { "$ref": "#/components/schemas/divisionResponse" } } } } } } } } } }, "/v1/trust-bundle/{trust_bundle_id}/divisions/limited": { "put": { "summary": "Update trust bundle limited by divisions", "operationId": "updateTrustBundleLimitedByDivisions", "tags": [ "Trust bundles" ], "description": "Use this endpoint to update trust bundle limited by division.\n", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleUpdateLimitedByDivisionRequest" } } } }, "responses": { "200": { "description": "Trust bundle object.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleResponse" } } } } } } }, "/v1/trust-bundle/{trust_bundle_id}/divisions/assign": { "put": { "summary": "Assign divisions to trust bundle", "operationId": "assignDivisionsToTrustBundle", "tags": [ "Trust bundles" ], "description": "Use this endpoint to assign divisions to trust bundle.\n", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleAssignDivisionsRequest" } } } }, "responses": { "204": { "description": "Divisions assigned to trust bundle. No content." } } } }, "/v1/trust-bundle/{trust_bundle_id}/divisions/remove": { "put": { "summary": "Remove divisions from trust bundle", "operationId": "removeDivisionsFromTrustBundle", "tags": [ "Trust bundles" ], "description": "Use this endpoint to remove divisions from trust bundle.\n", "parameters": [ { "$ref": "#/components/parameters/trust_bundle_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustBundleRemoveDivisionsRequest" } } } }, "responses": { "204": { "description": "Divisions removed from trust bundle. No content." } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "API key to authorize requests.", "name": "X-API-KEY", "in": "header" } }, "parameters": { "authentication_certificate_id": { "in": "path", "name": "authentication_certificate_id", "required": true, "description": "ID of the authentication certificate.", "schema": { "type": "string", "example": "a876d305-713c-4f0e-93c1-855a518f885e" } }, "certificate_id": { "in": "path", "name": "certificate_id", "description": "Certificate ID.", "required": true, "schema": { "type": "string", "example": "cf42d73e-bfe6-4854-9c2f-f62cd0148d3f" } }, "certificate_serial_number": { "in": "path", "name": "certificate_serial_number", "description": "Certificate serial number.", "required": true, "schema": { "type": "string", "example": "3031D3B7E49697B5BFF95F972E8C917D5A2BDE4D" } }, "certificate_value": { "in": "path", "name": "certificate_value", "description": "Certificate value.", "required": true, "schema": { "type": "string", "example": "Example IoT Device" } }, "device_id": { "in": "path", "name": "device_id", "required": true, "description": "Device ID.", "schema": { "type": "string", "example": "64c02969-3890-4da8-a5ef-b574fd72887e" } }, "device_identifier": { "in": "path", "name": "device_identifier", "required": true, "description": "The name of the device to query.", "schema": { "type": "string", "example": "Device name" } }, "division_id": { "in": "query", "name": "division_id", "required": true, "description": "The ID of the division for the device to query.", "schema": { "type": "string", "example": "d5faa1e-623a-47a9-831b-b9397c33395f" } }, "enrollment_profile_id": { "in": "path", "name": "enrollment_profile_id", "required": true, "description": "Enrollment profile ID.", "schema": { "type": "string", "example": "IOT_07ccbdc1-35d9-6ba2-7d3b-197b2c456088" } }, "format": { "in": "path", "name": "format", "description": "Certificate file format.\n - `DEFAULT` (application/zip) - Zip file with end-entity, intermediate, and root certificates with .crt extension. Supported for X.509 certificates.\n - `DEFAULT_CER` (application/zip) - Zip file with end-entity, intermediate, and root certificates with .cer extension. Supported for X.509 certificates.\n - `DEFAULT_PEM` (application/zip) - Zip file with end-entity, intermediate, and root certificates with .pem extension. Supported for X.509 certificates.\n - `DER` (application/zip) - Zip file with end-entity, intermediate, and root certificates with .der extension. Supported for X.509 certificates.\n - `PEM_ALL` (application/x-pem-file) - Single .pem file with end-entity, intermediate, and root certificates. Supported for X.509 certificates.\n - `PEM_NOROOT` (application/x-pem-file) - Single .pem file with end-entity and intermediate certificates. Supported for X.509 certificates.\n - `PEM_NOINTERMEDIATE` (application/x-pem-file) - Single .pem file with end-entity certificate. Supported for X.509 certificates.\n - `P7B` (application/x-pkcs7-certificates) - Single .p7b file with end-entity, intermediate, and root certificates. Supported for X.509 certificates.\n - `CER` (application/x-pkcs7-certificates) - Single .cer file with end-entity, intermediate, and root certificates with .cer extension. Supported for X.509 certificates.\n - `GP_ALL` (application/zip) - Zip file with end-entity in binary format and intermediate and root certificates with .crt extension. Supported for GlobalPlatform certificates.\n - `GP_BINARY` (application/global-platform-certificate) - Single end-entity certificate in binary format. Supported for GlobalPlatform certificates.\n - `GP_BINARY_ALL` (application/global-platform-certificate) - Zip file with end-entity, intermediate, and root certificates in binary format. Supported for GlobalPlatform certificates.\n", "required": true, "schema": { "type": "string", "enum": [ "DEFAULT", "DEFAULT_CER", "DEFAULT_PEM", "DER", "PEM_ALL", "PEM_NOROOT", "PEM_NOINTERMEDIATE", "P7B", "CER", "GP_ALL", "GP_BINARY", "GP_BINARY_ALL" ] } }, "batch_job_id": { "in": "path", "name": "job_id", "description": "Batch certificate enrollment job ID.", "required": true, "schema": { "type": "string", "example": "2202f2f8-6310-4744-acac-aec39acbc14c" } }, "import_job_id": { "in": "path", "name": "job_id", "description": "ID of the certificate import job.", "required": true, "schema": { "type": "string", "example": "67a3957e-0a29-4470-b694-c03ce42ed449" } }, "ocsp_group_id": { "in": "path", "name": "ocsp_group_id", "description": "OCSP group ID (UUID).", "required": true, "schema": { "type": "string", "example": "8063de41-0ac6-49c5-8ba2-10916e2db7da", "format": "uuid" } }, "trust_bundle_id": { "in": "path", "name": "trust_bundle_id", "description": "Trust bundle ID (UUID).", "required": true, "schema": { "type": "string", "example": "8063de41-0ac6-49c5-8ba2-10916e2db7da", "format": "uuid" } }, "passcode_id": { "in": "path", "name": "passcode_id", "required": true, "description": "Enrollment passcode ID.", "schema": { "type": "string", "example": "2ecc7a75-7b5e-4f40-9fe7-beafa716f255" } }, "pagination": { "in": "query", "name": "pagination", "description": "If true (default), the API calculates the total number of records and returns this number in the `total` response parameter. If false, the API does not calculate the total number of records, and the `total` response parameter returns `0`.\n\nSet this parameter to `false` to decrease response times when you don't need to know the total number of records. Calculating the total number of records for pagination increases response times.\n\n**Note:** To check if there is another page of records when `pagination` is `false`, use the `next` response parameter. If `next` is true, there is at least one more page of records that you can retrieve by increasing the `offset` in your next request. Otherwise, the current `records` list is the last page.\n", "schema": { "type": "boolean", "example": true, "default": true } } }, "schemas": { "createAcmeAuthenticationRequest": { "description": "Object with ACME credential data.", "type": "object", "required": [ "name", "account_id", "authentication_pem" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "Unique name for the credentials.", "example": "Custom name" }, "description": { "type": "string", "maxLength": 255, "description": "Custom description of the credentials.", "example": "Custom description" }, "account_id": { "description": "Your account ID. To get your account ID, sign in to your DigiCert® IoT Trust Manager account.", "type": "string", "maxLength": 36, "example": "e44757da-bdcc-5442-c568-734cc233281b" }, "external_account_binding": { "description": "If `true`, creates a new key identifier and HMAC key for ACME external account binding (EAB). When uploading the public key for an existing ACME credential, omit or use `false`.", "default": false, "type": "boolean", "example": true }, "authentication_pem": { "type": "string", "description": "PEM-encoded data for a public key or certificate corresponding to an existing private key for your ACME client. Required when `external_account_binding` is `false`.\n", "example": "-----BEGIN PUBLIC KEY-----..." }, "enrollment_profile": { "type": "string", "description": "ID of an enrollment profile to assign the credentials. Profile must support the ACME enrollment method. **Note:** If you do not assign credentials to an enrollment profile when you add them to your account, you can assign them later via your DigiCert® IoT Trust Manager account.", "maxLength": 40, "example": "IOT_502ac648-c826-4e71-991e-5629a23850c1" }, "start_date": { "type": "string", "example": "YYYY-MM-DD", "description": "Start date for the period of time during which you can use the credentials with the assigned `enrollment_profile`. No start date limit if not provided.", "format": "date-time" }, "end_date": { "type": "string", "example": "YYYY-MM-DD", "format": "date-time", "description": "End date for the period of time during which you can use the credentials with the assigned `enrollment_profile`. No end date limit if not provided." }, "usage_limit": { "type": "integer", "example": 100, "description": "Number of times the credentials can be used to request a certificate with the assigned `enrollment_profile`. No usage limit if not provided." }, "registered_values": { "type": "array", "items": { "$ref": "#/components/schemas/registered_value" } } } }, "account_id": { "description": "Account ID.", "type": "string", "format": "uuid", "example": "f92834ce-cdea-1584-b154-193bb198345e" }, "action": { "type": "string", "description": "The action performed on the resource.", "example": "create", "enum": [ "create", "update", "delete", "undelete", "disable", "enable", "enroll", "renew", "revoke" ] }, "authentication_type": { "type": "string", "example": "user", "enum": [ "user", "passcode", "certificate", "authentication_ca", "authentication_certificate" ] }, "certificate_profile_attributes": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/certificate_profile_attributes.id" }, "value": { "type": "string", "description": "Value for certificate attribute.", "example": "custom org name" } } }, "certificate_profile_attributes.id": { "type": "string", "example": "subject.common_name", "enum": [ "signature_algorithm", "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "validity.duration_unit", "validity.duration_value", "subject_identifier", "extensions.subject_directory", "validity.start_date_in_past_duration_unit", "validity.start_date_in_past_duration_value" ], "description": "ID of a certificate profile attribute.\n - `signature_algorithm` (X.509) - Signature algorithm\n - `subject.common_name` (X.509) - Common name\n - `subject.organization_name` (X.509) - Organization name\n - `subject.organization_unit` (X.509) - Organization unit\n - `subject.country` (X.509) - Country\n - `subject.locality` (X.509) - State\n - `subject.street_address` (X.509) - Street address\n - `subject.postal_code` (X.509) - Postal code\n - `subject.email` (X.509) - Email\n - `validity.duration_unit` (X.509, GlobalPlatform) - Validity period units\n - `validity.duration_value` (X.509, GlobalPlatform) - Validity period value\n - `subject_identifier` (X.509, GlobalPlatform) - GlobalPlatform certificate subject identifier. In the certificate template, if the encoding for the `subject_identifier` attribute is `auto`, certificate requests accept a 16-byte plain-text string `subject_identifier` value. If the encoding for the `subject_identifier` attribute is `hex_string`, certificate requests accept a 16-byte hex-string `subject_identifier` value.\n - `extensions.subject_directory` (X.509) - Information to store in the certificate's subject directory attributes (SDA) extension. The data structure and information to store in the SDA extension is formatted as a JSON string. For a description and examples of the SDA JSON object, see Subject directory attributes (SDA).\n - `validity.start_date_in_past_duration_unit` - (X.509) - units to specify validity start date in past from now (MINUTES, HOURS, DAYS, MONTHS, YEARS)\n - `validity.start_date_in_past_duration_value` - (X.509) - value to specify validity start date in past from now (positive integer value)\n" }, "chain": { "type": "array", "description": "List of objects with details about each certificate in the certificate chain. Each certificate in the `chain` array is signed by the certificate in the object that follows it.", "items": { "type": "object", "properties": { "common_name": { "type": "string", "description": "Certificate common name.", "example": "Issuing CA name" }, "type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "root", "intermediate" ] }, "status": { "type": "string", "description": "Certificate status.", "example": "ACTIVE", "enum": [ "ACTIVE", "PENDING_SIGN", "DISABLED" ] }, "start_date": { "type": "string", "format": "date", "description": "Start date of the certificate's validity period (UTC). Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2021-06-09T13:54:07Z" }, "end_date": { "type": "string", "format": "date", "description": "End date of the certificate's validity period (UTC). Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2051-06-09T13:06:23Z" }, "key_algorithm": { "type": "string", "description": "Certificate key algorithm.", "example": "RSA 2048", "enum": [ "RSA 2048", "RSA 3072", "RSA 4096", "EC prime256v1", "EC prime384v1", "EC prime521v1", "ED25519" ] }, "signature_algorithm": { "type": "string", "description": "Signature algorithm used to sign the certificate.", "example": "sha256WithRSA" }, "issuer_common_name": { "type": "string", "example": "Issuer common name", "description": "Common name of the issuing certificate." }, "body": { "type": "string", "description": "PEM-encoded certificate data.", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n" } } } }, "device_attributes": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the custom device attribute (corresponds to source field name in enrollment profile).", "example": "party-no" }, "value": { "type": "string", "description": "Value for custom device attribute.", "example": "PN8363454893" } } }, "division": { "type": "object", "description": "Object containing division name and ID.", "properties": { "id": { "$ref": "#/components/schemas/division_id" }, "name": { "type": "string", "description": "Division name.", "example": "Division name" } } }, "device_profile_id": { "type": "string", "description": "Device profile ID.", "format": "uuid", "example": "76b75066-628d-4002-9d1b-6d4e9418a12f" }, "division_id": { "type": "string", "description": "Division ID.", "example": "fd5faa1e-623a-47a9-831b-b9397c33395f" }, "enrollment_context": { "type": "object", "properties": { "enrollment_method": { "type": "string", "description": "Enrollment method for the imported certificates. For imported certificates, enrollment method is always `CERTIFICATE_IMPORT`.\n", "example": "CERTIFICATE_IMPORT" }, "ip_address": { "type": "string", "description": "IP address the client used for the certificate import job.", "example": "10.42.10.180" }, "authorization": { "type": "string", "description": "Authorization used for the certificate import job." }, "auth_type": { "type": "string", "description": "Type of authorization used for the certificate import job." } } }, "enrollment_profile": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/enrollment_profile_id" }, "name": { "type": "string", "description": "Enrollment profile name.", "example": "Enrollment Profile Name" } } }, "enrollment_profile_id": { "description": "Enrollment profile ID.", "type": "string", "example": "IOT_502ac648-c826-4e71-991e-5629a23850c1" }, "errorModel": { "type": "object", "properties": { "errors": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } ] } } } }, "limit": { "type": "integer", "description": "Limit on the number of records to include in the results.", "example": 20 }, "offset": { "type": "integer", "description": "Index of the first record.", "example": 0 }, "next": { "type": "boolean", "description": "If true, there is at least one more page of records. Otherwise, the current `records` list is the last page.", "example": false }, "pagination": { "type": "boolean", "description": "If true (default), the API calculates the total number of records and returns this number in the `total` response parameter. If false, the API does not calculate the total number of records, and the `total` response parameter returns `0`.\n\nThis parameter is modified using the `pagination` query parameter. If the list of supported parameters for an endpoint does not include the `pagination` query parameter, you cannot modify pagination behavior for the endpoint. For these endpoints, the API always calculates the total number of records and returns a `pagination` value of true.\n\n**Note:** To check if there is another page of records when `pagination` is `false`, use the `next` response parameter. If `next` is true, there is at least one more page of records that you can retrieve by increasing the `offset` in your next request. Otherwise, the current `records` list is the last page.\n" }, "total": { "type": "integer", "description": "Total number of records.\n\n**Note:** This parameter returns `0` if the `pagination` query string is false. In this case, use the `next` response parameter to check if there is another page of records.\n", "example": 1 }, "request_id": { "type": "string", "minLength": 20, "maxLength": 120, "example": "4170a427-c297-4508-9431-22e9f0fe7a9e", "description": "Custom ID between 20-120 characters to associate with the request.\n\nUse the `request_id` to avoid receiving duplicate certificates when the original request times out or the server does not respond.\n- If DigiCert® IoT Trust Manager receives multiple requests with the same `request_id` in the same 10 minute window, we return the certificate issued for the original request instead of issuing a new certificate.\n- If we receive a request with the same `request_id` as a request submitted more than 10 minutes ago, we issue a new certificate.\n\nIn addition to providing the same `request_id` value, requests must meet these conditions or DigiCert® IoT Trust Manager will issue a new certificate:\n- Requests using client-side keypair generation must use the same CSR as the original request.\n- Requests using server-side keypair generation must use the same private key encryption as the original request.\n" }, "note": { "type": "string", "maxLength": 255, "example": "Example certificate note", "description": "Custom note or description to help you manage the certificate. This note does not appear in the certificate itself. Character limit: 255.\n" }, "resource_type": { "description": "Resource type.", "type": "string", "example": "division", "enum": [ "device", "division", "certificate", "certificate_request", "enrollment_profile", "enrollment_profile_passcode", "enrollment_profile_mapping", "enrollment_profile_source_field", "authentication_certificate", "device_profile", "certificate_template", "certificate_profile" ] }, "auditLogRecordObject": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the audit log event.", "example": "2ec5c201-7b2a-1dce-b23f-143a12eb123c" }, "account_id": { "$ref": "#/components/schemas/account_id" }, "division_id": { "$ref": "#/components/schemas/division_id" }, "resource_type": { "$ref": "#/components/schemas/resource_type" }, "resource_name": { "type": "string", "description": "The name of the resource.", "example": "Resource name." }, "resource": { "type": "string", "description": "Unique ID of the resource.", "example": "Resource ID" }, "authentication_type": { "$ref": "#/components/schemas/authentication_type" }, "authentication_id": { "type": "string", "description": "The unique ID of the authentication object associated with the record. This can be the ID of a user, passcode, certificate, authentication certificate authority (CA), or authentication certificate.", "example": "530666e8-8c9a-44b9-9984-e25f3c82e2b5" }, "authentication": { "type": "string", "description": "The name of the authentication object associated with the event that created the audit log record.", "example": "example@email.com" }, "action": { "$ref": "#/components/schemas/action" }, "description": { "type": "string", "description": "Short description of the audit log event.", "example": "Description of the audit log event" }, "status": { "type": "string", "description": "Status of the request that created the audit log event.", "enum": [ "success", "failed" ] } } }, "deviceResponseObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique device ID.", "example": "64c02969-3890-4da8-a5ef-b574fd72887e" }, "account_id": { "$ref": "#/components/schemas/account_id" }, "division": { "$ref": "#/components/schemas/division" }, "device_identifier": { "type": "string", "description": "Unique device name. Character limit: 255", "maxLength": 255, "example": "Device name" }, "device_profile": { "type": "object", "description": "Object with details about the device profile associated with the device.", "properties": { "id": { "type": "string", "description": "Device profile ID.", "example": "a81a431a-be7b-4f2e-8afd-b2778491511f" }, "name": { "type": "string", "description": "Device profile name.", "example": "Device profile name" } } }, "created": { "type": "string", "format": "date-time", "description": "Date and time device was created. Format: UTC timezone and ISO 8601 format.\n" }, "updated": { "type": "string", "format": "date-time", "description": "Date and time device was last updated. Format: UTC timezone and ISO 8601 format.\n" }, "status": { "type": "string", "description": "Device status.", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "fields": { "type": "array", "description": "Array of objects with key/value pairs that describe device attributes and settings.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Field ID as defined in the device profile.", "example": "123c456e-789c-1e23-4567-ee90f39458fb" }, "name": { "type": "string", "description": "Field name.", "example": "Field name" }, "value": { "type": "string", "description": "Field value.", "example": "Field value" }, "mandatory": { "type": "boolean", "description": "Whether or not the field is required, based on the device profile." } } } }, "device_api_allow_read": { "type": "boolean", "description": "If true, the device can read its own device information by submitting a request to the `GET /v2/device/{device_id}` or `GET /v3/device/{device_identifier}` endpoints. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true }, "device_api_allow_write": { "type": "boolean", "description": "If true, the device can update its own device information by submitting a request to the `PUT /v2/device/{device_id}` or `PUT /v3/device/{device_identifier}` endpoints. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true }, "device_api_allow_renew_certificate": { "type": "boolean", "description": "If true, the device can renew its own certificates by submitting a request to the `POST /v2/device/{device_id}/renew` or `POST /v3/device/{device_identifier}/renew` endpoints. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true }, "device_api_allow_revoke": { "type": "boolean", "description": "If true, the device can revoke its own certificates by submitting a request to the `POST /v2/device/{device_id}/revoke` or `POST /v3/device/{device_identifier}/revoke` endpoints. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true } } }, "deviceCertificateResponseObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique certificate ID.", "example": "64c02969-3890-4da8-a5ef-b574fd72887e" }, "common_name": { "type": "string", "description": "Certificate common name.", "example": "Common Name" }, "serial_number": { "$ref": "#/components/schemas/certificate_serial_number" }, "body": { "type": "string", "description": "PEM-encoded certificate.", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n" }, "valid_from": { "description": "Start date of certificate validity period. Format: UTC timezone and ISO 8601 date.\n", "type": "string", "format": "date-time", "example": "YYYY-MM-DDThh:mm:ss.sTZD" }, "valid_to": { "description": "End date of certificate validity period. Format: UTC timezone and ISO 8601 date.\n", "type": "string", "format": "date-time", "example": "YYYY-MM-DDThh:mm:ss.sTZD" }, "status": { "description": "Certificate status.", "type": "string", "enum": [ "ISSUED", "REVOKED", "EXPIRED" ] }, "chain": { "type": "array", "description": "List of objects with details about each certificate in the certificate chain. Each certificate in the `chain` array is signed by the certificate in the object that follows it.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "cert_type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "blob": { "type": "string", "description": "Certificate body in PEM format.", "example": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\n" }, "common_name": { "type": "string", "description": "Certificate common name.", "example": "Issuing CA name" } } } } } }, "failedRequestDetails": { "allOf": [ { "$ref": "#/components/schemas/auditLogRecordObject" }, { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the request that created the audit log event.", "example": "failed", "enum": [ "success", "failed" ] }, "error_message": { "type": "string", "description": "Short error message. Only returned when the `status` property has a value of `failed`.", "example": "Error message" }, "detailed_error_message": { "type": "string", "description": "Detailed error message. Only returned when the `status` property has a value of `failed`.", "example": "Detailed error message." }, "request": { "type": "string", "description": "The body of the request that created the audit log event, formatted as a JSON string. Only returned when the `status` property has a value of `failed`.", "example": "{\"name\":\"New Division\",\"account_id\":\"123a456c-7a89-1234-5678-1885a36b6609\"}" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of the event. Format: UTC timezone and ISO 8601 format.\n", "example": "2020-11-05T08:36:50Z" } } } ] }, "successfulRequestDetails": { "allOf": [ { "$ref": "#/components/schemas/auditLogRecordObject" }, { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the request that created the audit log event.", "example": "success", "enum": [ "success", "failed" ] }, "properties": { "type": "array", "description": "List of objects with details about each resource property. Use the `properties` array to find the value of each property before and after the audit log event. Only returned when the status property has a value of `success`.", "items": { "oneOf": [ { "$ref": "#/components/schemas/propertyDetails" }, { "$ref": "#/components/schemas/changedPropertyDetails" } ] } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of the event. Format: UTC timezone and ISO 8601 format.\n", "example": "2020-11-05T08:36:50Z" } } } ] }, "enrollmentPasscodeObject": { "properties": { "name": { "type": "string", "description": "Passcode name.", "maxLength": 64, "example": "Passcode name" }, "description": { "type": "string", "description": "Custom passcode description.", "maxLength": 255, "example": "Custom passcode description." }, "validity_period": { "type": "object", "description": "Object that defines the period of time during which the passcode can be used.", "properties": { "from": { "type": "string", "description": "Start date of passcode validity period. If not provided, the passcode can be used immediately. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-01-01" }, "to": { "type": "string", "description": "End date of passcode validity period. If not provided, the passcode does not expire. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-06-01" } } }, "passcode_length": { "type": "integer", "description": "Number of characters in the passcode. Only returned for passcodes generated by DigiCert® IoT Trust Manager.\n\n**Note:** For enrollment profiles using the SCEP enrollment method, passcode length is fixed at 20 characters.\n", "maxLength": 64, "minLength": 20, "default": 27 }, "generation_option": { "type": "string", "description": "If `AUTO` (default), DigiCert® IoT Trust Manager generated the passcode. If `PROVIDED`, a user provided the passcode.", "enum": [ "AUTO", "PROVIDED" ] }, "usage_limit": { "type": "integer", "description": "Number of times the passcode can be used.", "example": 100 }, "status": { "type": "string", "description": "Passcode status.", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "registered_values": { "type": "array", "description": "List of objects with details about the certificate fields that are validated when using this passcode. Not returned if there are no registered values associated with the passcode.", "items": { "type": "object", "properties": { "certificate_field": { "type": "string", "description": "Name of a certificate field to validate when using this passcode.", "example": "subject.common_name", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "challenge_password" ] }, "matcher": { "type": "string", "description": "Operator used when comparing the value of the certificate field to the registered values.", "enum": [ "equals" ], "example": "equals" }, "value": { "description": "A value or list of values to compare with the value of the chosen `certificate_field`. Use a string to validate certificate fields that contain a string. Use an array to validate certificate fields that contain an array.", "oneOf": [ { "type": "string" }, { "type": "array", "items": {} } ] }, "multiple": { "type": "boolean", "description": "Returns `true` when the data type of the certificate field is an array. Otherwise, `false`.", "example": false } } } }, "enable_username_for_passcode": { "type": "boolean", "description": "If true, the option to add a username is enabled for the enrollment passcode. Otherwise, false (default). To associate a username with the enrollment passcode, the enrollment profile must use the EST or CMPv2 enrollment method." }, "username": { "type": "string", "description": "Enrollment passcode username. Usernames have 1-64 characters and are unique within the enrollment profile. The `username` parameter is only returned if a username is associated with the enrollment passcode.", "example": "username_example", "maxLength": 64 }, "id": { "type": "string", "description": "Unique ID of the passcode.", "example": "2ecc7a75-7b5e-4f40-9fe7-beafa716f255" }, "enrollment_profile": { "$ref": "#/components/schemas/enrollment_profile" }, "device_profile": { "type": "object", "description": "Object with details about the device profile associated with the passcode.", "properties": { "id": { "type": "string", "description": "Device profile ID.", "example": "a81a431a-be7b-4f2e-8afd-b2778491511f" }, "name": { "type": "string", "description": "Device profile name.", "example": "Device profile name" } } }, "division": { "$ref": "#/components/schemas/division" }, "account_id": { "$ref": "#/components/schemas/account_id" }, "passcode": { "type": "string", "description": "Passcode.", "example": "H2QDEBTWC***********" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time the passcode was created. Format: UTC timezone and ISO 8601 date.\n", "example": "2020-10-02T21:16:02Z" }, "number_of_usage": { "type": "integer", "description": "Number of times the passcode has been used.", "example": 0 }, "enrollment_methods": { "type": "array", "description": "List of enrollment methods for the passcode's enrollment profile.", "items": { "type": "string", "description": "Enrollment method.", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH", "EXTERNAL_BATCH" ] }, "example": [ "CMP_V2" ] } } }, "authenticationCertificateResponse": { "allOf": [ { "type": "object", "properties": { "template_id": { "type": "string", "description": "ID of the authentication CA template." }, "id": { "type": "string", "description": "Authentication certificate ID.", "example": "a876d305-713c-4f0e-93c1-855a518f885e" }, "name": { "type": "string", "description": "Friendly name for the authentication certificate.", "example": "Example Name" }, "enrollment_profile": { "$ref": "#/components/schemas/enrollment_profile" }, "start_date": { "type": "string", "description": "Start date for the period of time during which the enrollment profile can use the authentication certificate. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-01-01" }, "end_date": { "type": "string", "description": "End date for the period of time during which the enrollment profile can use the authentication certificate. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-06-01" }, "usage_limit": { "type": "string", "description": "Number of times the authentication certificate can be used. If not provided, the authentication certificate does not have a usage limit.", "example": 0 }, "registered_values": { "type": "array", "description": "List of objects with details about the certificate fields to validate when using this authentication certificate. Not returned if there are no registered values associated with the certificate.", "items": { "type": "object", "properties": { "certificate_field": { "type": "string", "description": "Name of a certificate field to validate when using this passcode.", "example": "subject.common_name", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "challenge_password" ] }, "matcher": { "type": "string", "description": "Operator used when comparing the value of the certificate field to the registered values.", "enum": [ "equals" ], "example": "equals" }, "value": { "description": "A value or list of values to compare with the value of the chosen `certificate_field`. Use a string to validate certificate fields that contain a string. Use an array to validate certificate fields that contain an array.", "oneOf": [ { "type": "string" }, { "type": "array", "items": {} } ] }, "multiple": { "type": "boolean", "description": "Returns `true` when the data type of the certificate field is an array. Otherwise, `false`.", "example": false } } } }, "number_of_usage": { "type": "string", "description": "Number of times the authentication certificate has been used.", "example": 0 }, "status": { "type": "string", "description": "Authentication certificate status.", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time the authentication certificate was assigned. Format: UTC timezone and ISO 8601 date.\n", "example": "2020-10-02T21:16:02Z" }, "certificate_issuer_common_name": { "type": "string", "description": "Common name of the certificate issuer.", "example": "IoT Issuing CA" }, "use_passcode": { "type": "boolean", "description": "If `true`, clients authenticating with these credentials must also provide a passcode in the `x-passcode` request header. Otherwise, no passcode is required.\n", "example": false }, "generation_option": { "type": "string", "description": "If `use_passcode` is `true`, the response contains the passcode generation option. Omitted otherwise.\n\n* `AUTO`: DigiCert® IoT Trust Manager generated the passcode.\n* `PROVIDED`: A user provided the passcode.\n" }, "passcode": { "description": "If `use_passcode` is `true`, the response contains the passcode value. Omitted otherwise.\n\nWhen adding or updating an authentication certificate:\n* If `generation_option` is `PROVIDED`, the passcode is masked.\n\n* If `generation_option` is `AUTO`, returns generated passcode. In subsequent requests to retrieve details about the authentication certificate, the passcode is masked.\n", "minLength": 6, "maxLength": 64, "type": "string", "example": "ExamplePasscode123" }, "passcode_length": { "type": "integer", "description": "If `use_passcode` is `true`, the response contains the passcode length. Omitted otherwise.\n", "minLength": 20, "maxLength": 64, "example": 20 } } } ], "anyOf": [ { "type": "object", "properties": { "certificate": { "type": "object", "description": "Object with information about the certificate.", "properties": { "id": { "type": "string", "description": "Certificate ID.", "example": "0dd83c6a-63c2-4d52-acc9-7140e0fb0332" }, "name": { "type": "string", "description": "Certificate name.", "example": "AuthCert001" } } } } }, { "type": "object", "properties": { "certificate_attributes": { "type": "array", "description": "List of objects that define required attributes for an authentication certificate.", "items": { "type": "object", "properties": { "certificate_attribute": { "type": "string", "description": "Certificate attribute name.", "example": "subject.common_name", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "subject.unique_identifier" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "description": "Expected value of the certificate attribute.", "example": "subject common name" }, "multiple": { "type": "boolean", "description": "If true, data type of the certificate field is an array. Otherwise, false.", "example": false } } } } } } ], "oneOf": [ { "type": "object", "properties": { "pem": { "type": "string", "description": "Certificate body, in PEM format." }, "certificate_expires_on": { "type": "string", "description": "Date and time the certificate expires. Format: UTC timezone and ISO 8601 date.\n", "example": "2021-03-03T10:19:17Z" }, "certificate_serial_number": { "type": "string", "description": "Certificate serial number.", "example": "57db86ca2713c7060aa43971ef32f598c1521c56" }, "certificate_thumbprint": { "type": "string", "description": "Thumbprint of the certificate.", "example": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143" }, "certificate_organization": { "type": "string", "description": "Organization associated with the certificate.", "example": "DigiCert" }, "certificate_organization_units": { "type": "array", "description": "List of organization units associated with the certificate.", "items": { "type": "string" } } } } ] }, "propertyDetails": { "type": "object", "properties": { "name": { "type": "string", "description": "Property name.", "example": "Property name" }, "changed": { "type": "boolean", "description": "Whether the event changed the value of the property.", "example": false }, "value_after": { "type": "string", "description": "The value of the property after the event. Always returned, even if the value did not change." } } }, "changedPropertyDetails": { "allOf": [ { "$ref": "#/components/schemas/propertyDetails" }, { "type": "object", "properties": { "value_before": { "type": "string", "description": "The value of the property before the event. Only returned when the changed `property` has a value of `true`." }, "changed": { "type": "boolean", "description": "Whether the event changed the value of the property.", "example": true } } } ] }, "certificateDetails": { "type": "object", "properties": { "id": { "description": "Certificate ID.", "type": "string", "example": "197046ba-25fe-45ed-a590-752734f45146" }, "device": { "type": "object", "description": "Object with device name and ID.", "properties": { "id": { "type": "string", "description": "Device ID.", "format": "uuid", "example": "52245507-3cc8-4737-a345-1b88a8be926a" }, "name": { "type": "string", "description": "Device name.", "example": "Example device" } } }, "device_profile": { "type": "object", "description": "Object with device profile name and ID.", "properties": { "id": { "$ref": "#/components/schemas/device_profile_id" }, "name": { "type": "string", "description": "Device profile name.", "example": "Example device profile" } } }, "serial_number": { "$ref": "#/components/schemas/certificate_serial_number" }, "thumbprint_sha256": { "type": "string", "description": "Certificate SHA256 thumbprint.", "example": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143" }, "ca_id": { "type": "string", "description": "ID of the end-entity certificate in DigiCert® CA Manager.", "example": "AAC2E2DD6BEAE2E5EE93954BAE15E34D" }, "created": { "type": "string", "description": "Date and time (UTC) the certificate was created.", "format": "date-time", "example": "YYYY-MM-DDThh:mm:ss.sTZD" }, "body": { "description": "Certificate body in PEM format.", "type": "string", "example": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\n" }, "status": { "description": "Certificate status.", "type": "string", "enum": [ "ISSUED", "REVOKED", "EXPIRED" ] }, "common_name": { "description": "Certificate common name.", "type": "string", "example": "Example common name" }, "enrollment_method": { "type": "string", "description": "Enrollment method used to create the certificate.\n", "example": "API", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH", "EXTERNAL_BATCH" ] }, "valid_from": { "description": "Start date of certificate validity period. Format: UTC timezone and ISO 8601 date.\n", "type": "string", "format": "date-time", "example": "YYYY-MM-DDThh:mm:ss.sTZD" }, "valid_to": { "description": "End date of certificate validity period. Format: UTC timezone and ISO 8601 date.\n", "type": "string", "format": "date-time", "example": "YYYY-MM-DDThh:mm:ss.sTZD" }, "certificate_request_id": { "description": "Certificate request ID.", "type": "string", "format": "uuid", "example": "fbbf3496-2f9c-4329-9bc4-f0e512ceecb2" }, "renewed": { "type": "boolean", "description": "If true, the certificate has been renewed. Otherwise, false.", "example": false }, "managed": { "type": "boolean", "description": "If true, the certificate is \"managed\" and can be revoked. Otherwise, false.\n", "example": true }, "chain": { "type": "array", "description": "List of objects with details about each certificate in the certificate chain. Each certificate in the `chain` array is signed by the certificate in the object that follows it.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "cert_type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "blob": { "type": "string", "description": "Certificate body in PEM format.", "example": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\n" }, "common_name": { "type": "string", "description": "Certificate common name.", "example": "Issuing CA name" } } } }, "renew_allowed": { "type": "boolean", "description": "If true, the certificate can be renewed. Otherwise, false.", "example": true }, "certificate_value": { "type": "string", "description": "Certificate value.", "example": "My Device Cert" }, "issuer_common_name": { "type": "string", "example": "Issuing CA common name", "description": "Common name of the issuing certificate." }, "signature_algorithm": { "type": "string", "description": "Certificate signature algorithm.", "example": "sha256WithRSA", "enum": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA" ] }, "key_type": { "type": "string", "description": "Certificate key type.", "example": "RSA_2048", "enum": [ "RSA_2048", "RSA_3072", "RSA_4096", "P_256", "P_384", "P_512", "ED_25519" ] }, "certificate_format": { "type": "string", "description": "Certificate format.", "enum": [ "x509", "global-platform", "attribute-certificate" ], "example": "x509" }, "enrollment_profile_id": { "$ref": "#/components/schemas/enrollment_profile_id" }, "enrollment_profile_name": { "type": "string", "description": "Enrollment profile name.", "example": "Example enrollment profile." }, "account_id": { "$ref": "#/components/schemas/account_id" }, "division_id": { "$ref": "#/components/schemas/division_id" }, "ca_issuer_id": { "type": "string", "description": "ID of issuing CA certificate in DigiCert® CA Manager.", "example": "BBD2E2DD6BEAE2E5EE93954BAE15E34D" }, "issuer_serial_number": { "type": "string", "description": "Issuing CA serial number.", "example": "1234D1B7345647B5B6F95F572E8C917D5A123456" }, "ocsp_group_id": { "type": "string", "description": "ID of OCSP group the certificate belongs to. Omitted if the certificate is not in an OCSP group.\n", "example": "6c43772a-5c95-4f38-bc2a-96b8ef32d478", "format": "uuid" }, "ocsp_group_name": { "type": "string", "description": "Name of OCSP group the certificate belongs to. Omitted if the certificate is not in an OCSP group.", "example": "Example OCSP group" }, "certificate_type": { "type": "string", "description": "Certificate type.", "enum": [ "end_entity", "intermediate", "root" ], "example": "end_entity" }, "key_usage": { "type": "string", "description": "Comma-separated list of the certificate's key usage extensions.", "example": "digital_signature, key_encipherment" }, "extended_key_usage": { "type": "string", "description": "Comma-separated list of the certificate's extended key usage (EKU) extensions.", "example": "client_authentication" }, "authentication_id": { "type": "string", "format": "uuid", "description": "ID of the authentication used to request the certificate. This can be the ID of a user, passcode, certificate, authentication certificate authority (CA), or authentication certificate.", "example": "5718b6d0-d861-4552-a5a9-dffdeee994ce" }, "authentication_type": { "type": "string", "description": "Authentication type used to request the certificate.", "example": "user", "enum": [ "user", "passcode", "certificate", "authentication_ca", "authentication_certificate" ] }, "authentication_name": { "type": "string", "description": "Authentication name.", "example": "local.admin" }, "ca_connector_type": { "type": "string", "description": "CA connector type. Possible values: `digicert_one` (DigiCert® Account Manager) or `digicert_cis` (CertCentral CIS API).\n", "enum": [ "digicert_one", "digicert_cis" ] }, "note": { "type": "string", "maxLength": 255, "example": "Example certificate note", "description": "Custom note or description to help you manage the certificate. This note does not appear in the certificate itself. Character limit: 255.\n" } } }, "limitedCertificateDetails": { "type": "object", "properties": { "id": { "description": "Certificate ID.", "type": "string", "example": "197046ba-25fe-45ed-a590-752734f45146" }, "common_name": { "description": "Certificate common name.", "type": "string", "example": "Example common name" }, "serial_number": { "$ref": "#/components/schemas/certificate_serial_number" }, "body": { "description": "Certificate body.", "type": "string", "example": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\n" }, "valid_from": { "description": "Start date of certificate validity period. Format: UTC timezone and ISO 8601 date.\n", "type": "string", "format": "date-time", "example": "2020-12-01T23:44:39Z" }, "valid_to": { "description": "End date of certificate validity period. Format: UTC timezone and ISO 8601 date.\n", "type": "string", "format": "date-time", "example": "2021-04-30T21:24:12Z" }, "status": { "description": "Certificate status.", "type": "string", "enum": [ "ISSUED", "REVOKED", "EXPIRED" ], "example": "ISSUED" } } }, "certificate_serial_number": { "description": "Certificate serial number.", "type": "string", "example": "1234D1B7345647B5B6F95F572E8C917D5A123456" }, "importJobDetailsObject": { "type": "object", "properties": { "id": { "description": "Unique ID for the certificate import job.", "type": "string", "example": "67a3957e-0a29-4470-b694-c03ce42ed449" }, "random_id": { "description": "Random ID associated with the certificate import job.", "type": "string", "example": "687338079509" }, "enrollment_profile": { "$ref": "#/components/schemas/enrollment_profile" }, "original_file_name": { "description": "Name of the uploaded file.", "type": "string", "example": "certificates_xml.zip" }, "format": { "description": "Format of the imported files.", "type": "string", "example": "XML", "enum": [ "XML", "PEM" ] }, "original_size": { "type": "integer", "description": "Size of the uploaded file, in bytes.", "example": 1042 }, "stored_file_name": { "type": "string", "description": "Name of the file after it is uploaded.", "example": "certificate-import-687338079509.zip" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp for the beginning of the import job. Format: UTC timezone and ISO 8601 date.\n", "example": "2020-08-11T20:25:31.943335Z" }, "status": { "type": "string", "description": "Status of the import job.", "example": "COMPLETED", "enum": [ "PENDING", "COMPLETED" ] }, "enrollment_context": { "$ref": "#/components/schemas/enrollment_context" }, "total_certificates": { "type": "integer", "description": "Total number of certificates processed.", "example": 3 }, "failed_certificates": { "type": "integer", "description": "Number of certificates that failed to import.", "example": 0 }, "processing_time": { "type": "integer", "description": "Processing time of the import job, in milliseconds.", "example": 0 } } }, "enrollmentResponseObject": { "type": "object", "properties": { "certificate_request_id": { "description": "Certificate request ID.", "type": "string", "example": "fbbf3496-2f9c-4329-9bc4-f0e512ceecb2" }, "status": { "type": "string", "description": "Request status.", "enum": [ "PENDING_APPROVAL", "APPROVED", "AUTO_APPROVED", "REJECTED", "CANCELED" ] }, "result": { "type": "string", "description": "Certificate enrollment status.", "enum": [ "SUCCESS", "FAILED" ] }, "certificate_id": { "description": "Certificate ID.", "type": "string", "example": "66666666-7777-8888-9999-000000000000" }, "pem": { "type": "string", "description": "PEM-encoded certificate data.\n\nWhen the `split_certificate_response` option is set to false (default), the `pem` field contains data for the entire certificate chain (for example, end-entity certificate, intermediate CA certificate, and root certificate).\n\nWhen the `split_certificate_response` option is set to true, the `pem` field only contains the end-entity certificate. The intermediate CA and root certificates return in the `chain` array.\n", "example": "" }, "ica": { "type": "string", "description": "Issuing intermediate CA certificate.", "example": "MII..." }, "chain": { "type": "array", "description": "List of objects containing the intermediate CA and root certificates from the certificate chain. Each certificate in the `chain` array is signed by the certificate in the object that follows it.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "body": { "type": "string", "description": "PEM-encoded certificate data.", "example": "" } } } }, "private_key": { "type": "string", "description": "For certificate requests and renewals using server-side keypair generation, this parameter returns the private key in the requested format (`private_key_format`). Only returned if the response data is formatted as a JSON object.\n", "example": "" } } }, "downloadBatchCertificateResponseObject": { "type": "object", "properties": { "certificate_id": { "type": "string", "description": "Certificate ID (UUID).", "example": "b5db525b-fff8-44de-abab-fd4e8b68f2c5" }, "format": { "description": "Download format.", "type": "string", "example": "pem", "enum": [ "pem", "pkcs12" ] }, "certificate": { "type": "string", "description": "PEM-encoded certificate data. Only returned if download `format` is `pem`." }, "private_key": { "type": "string", "description": "PEM-encoded private key data. Only returned if download `format` is `pem`." }, "chain": { "type": "array", "description": "List of objects containing the intermediate CA and root certificates from the certificate chain. Each certificate in the `chain` array is signed by the certificate in the object that follows it. Only returned if download format is `pem`.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "cert_type": { "type": "string", "description": "Certificate type (root or intermediate)", "enum": [ "root", "intermediate" ] }, "blob": { "type": "string", "description": "Certificate data." } } } }, "pkcs12": { "type": "string", "description": "Base 64 encoded PKCS12 file containing the certificate and private key. Only returned if download format is `pkcs12`." }, "pkcs12_password": { "type": "string", "description": "Password that protects the PKCS12 file. Only returned if download `format` is `pkcs12`." } } }, "registered_value": { "type": "object", "description": "List of objects with details about the certificate fields to validate when using these credentials with the assigned enrollment profile. If you don't need to validate certificate fields for these credentials, omit the `registered_values` object from your request.", "properties": { "certificate_field": { "type": "string", "description": "Name of a certificate field to validate when using the credentials.", "example": "subject.common_name", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "challenge_password" ] }, "matcher": { "type": "string", "description": "Operator used when comparing the value of the certificate field to the registered values.", "enum": [ "equals" ], "example": "equals" }, "value": { "description": "A value or list of values to compare with the value of the chosen `certificate_field`. Use a string to validate certificate fields that contain a string. Use an array to validate certificate fields that contain an array.", "example": "example", "oneOf": [ { "type": "string", "example": "example" }, { "type": "array", "items": {}, "example": [ "example1", "example2" ] } ] } } }, "acmeAuthenticationResponseObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Key identifier (KID) for external account binding.", "example": "341fc43b-02b1-4379-abe7-ea1f4aa1928b" }, "name": { "type": "string", "maxLength": 255, "description": "Unique name for the credentials.", "example": "Custom name" }, "description": { "type": "string", "maxLength": 255, "description": "Custom description of the credentials.", "example": "Custom description" }, "account_id": { "description": "ID of the account the credentials belong to.", "type": "string", "maxLength": 36, "example": "e44757da-bdcc-5442-c568-734cc233281b" }, "authentication_pem": { "type": "string", "description": "PEM-encoded data for a public key or certificate corresponding to an existing private key for your ACME client. Required when `external_account_binding` is `false`.", "example": "-----BEGIN PUBLIC KEY-----..." }, "authentication_type": { "description": "Authentication type of the uploaded PEM data.", "type": "string", "enum": [ "public_key", "certificate" ], "example": "certificate" }, "thumbprint": { "description": "Thumbprint of the uploaded certificate or public key.", "type": "string", "example": "9e00a421268a1e814805cb0571a157d2fdbd9b48a02286c77d4e76110727727d" }, "status": { "type": "string", "description": "ACME credential status.", "enum": [ "ACTIVE", "DISABLED", "DELETED" ], "example": "ACTIVE" }, "created_at": { "description": "Date and time (UTC) the credentials were added.", "type": "string", "format": "date-time", "example": "YYYY-MM-DDThh:mm:ss.sTZD" }, "key_type": { "description": "Key type of the uploaded certificate or public key.", "type": "string", "enum": [ "RSA", "EC" ], "example": "RSA" }, "rsa_key_size": { "description": "If `key_type` is `RSA`, returns the key size of the uploaded certificate or public key.", "type": "integer", "format": "int32" }, "ecdsa_curve": { "description": "If `key_type` is `EC`, returns the ECDSA curve for the uploaded certificate or public key.", "type": "string" }, "key_description": { "type": "string", "description": "Description of the uploaded certificate or public key." }, "certificate_common_name": { "description": "Common name on the uploaded certificate.", "type": "string", "example": "example_common_name" }, "issuer_common_name": { "description": "Common name on the intermediate certificate authority (ICA) that issued the uploaded certificate.", "type": "string", "example": "example_issuing_certificate" }, "hmac_key": { "description": "HMAC key for external account binding.", "example": "FS3f8Q7yUZQQO4uLUP8vAyREMCKyUqRr7JoHy1aquKiPYwu42r67CcELWlYRy9oJyzJ09n5oojJzz9t0EhWiNQ", "type": "string" }, "external_account_binding": { "description": "If `true`, these credentials include a key identifier and HMAC key that you can use with an ACME client that supports external account binding. Otherwise, `false`.", "type": "boolean", "example": true }, "account_bind": { "description": "Returns `true` when the key identifier and ACME key credentials have been registered with an ACME client.", "type": "boolean" }, "public_key_pem": { "description": "PEM-encoded data for the public key.", "example": "----BEGIN PUBLIC KEY-----...", "type": "string" } } }, "addAuthenticationCertificateRequest": { "allOf": [ { "type": "object", "required": [ "template_id", "name" ], "properties": { "template_id": { "type": "string", "format": "uuid", "description": "ID of the authentication CA template (UUID). Sourced from **List authentication CA templates** API endpoint.\n", "example": "b6ef681d-a051-4135-b010-7e8a0dde55eb" }, "name": { "type": "string", "description": "Friendly name for the authentication certificate.", "example": "Example Name" }, "start_date": { "type": "string", "description": "Start date for the period of time during which the enrollment profile can use the authentication certificate. Can be earlier than the certificate’s \"valid from\" date. If not provided, there is no start date limitation. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-01-01" }, "end_date": { "type": "string", "description": "End date for the period of time during which the enrollment profile can use the authentication certificate. Can be later than the certificate’s \"valid to\" date. If not provided, there is no end date limitation. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-06-01" }, "usage_limit": { "type": "number", "description": "Number of times the authentication certificate can be used. If not provided, the authentication certificate does not have a usage limit.", "example": 0 }, "registered_values": { "type": "array", "items": { "$ref": "#/components/schemas/registered_value" } }, "use_passcode": { "type": "boolean", "description": "If `true`, clients authenticating with these credentials must also provide a passcode in the `x-passcode` request header. Otherwise, no passcode is required.\n\n**Note:** This parameter must have a `true` value if the authentication CA template requires passcodes for authentication certificates (`\"force_passcode_for_auth_cert\" = \"true\"`.\n", "default": false }, "generation_option": { "type": "string", "description": "Passcode generation option. Required if `use_passcode` is `true`.\n\n* `AUTO`: DigiCert® IoT Trust Manager generates the passcode.\n* `PROVIDED`: Provide the passcode in your request.\n" }, "passcode": { "description": "Passcode. Must be between 6 and 64 characters. Required if `generate_option` is `PROVIDED`.", "minLength": 6, "maxLength": 64, "type": "string", "example": "ExamplePasscode123" }, "passcode_length": { "type": "integer", "description": "Number of characters in the passcode generated by DigiCert® IoT Trust Manager. Required if `generate_option` is `AUTO`.", "minLength": 20, "maxLength": 64, "example": 20 } } } ], "oneOf": [ { "type": "object", "required": [ "certificate_attributes" ], "properties": { "certificate_attributes": { "type": "array", "description": "List of objects that define required attributes for an authentication certificate.", "items": { "type": "object", "properties": { "certificate_attribute": { "type": "string", "description": "Certificate attribute name.", "example": "subject.common_name", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "description": "Expected value of the certificate attribute.", "example": "subject common name" }, "multiple": { "type": "boolean", "description": "If true, data type of the certificate field is an array. Otherwise, false.", "example": false } } } } } }, { "type": "object", "required": [ "pem" ], "properties": { "pem": { "type": "string", "description": "Certificate body of the authentication certificate, in PEM format." } } } ] }, "enrollmentProfileResponse": { "description": "Object containing enrollment profile details.", "type": "object", "properties": { "name": { "type": "string", "description": "Enrollment profile name.", "example": "Example name" }, "enrollment_methods": { "type": "array", "description": "List of enrollment methods enabled for the profile.", "items": { "type": "string", "description": "Enrollment method.", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH", "EXTERNAL_BATCH" ] }, "example": [ "API", "PORTAL" ] }, "allowed_ip_addresses": { "type": "array", "description": "List of IP addresses allowed to request certificates using the enrollment profile.", "items": { "type": "string", "example": "1.1.1.1" }, "example": [ "1.1.1.1", "2.2.2.2" ] }, "allowed_hours_from": { "type": "string", "description": "Daily start time in the specified `timezone` (UTC if no `timezone` is set) for when certificates can be requested through the enrollment profile. Only returned if an `allowed_hours_from` value is set for the profile. Format: `HH:MM:SS`\n", "format": "date", "example": "09:45:00" }, "allowed_hours_to": { "type": "string", "description": "Daily end time in the specified `timezone` (UTC if no `timezone` is set) for when certificates can be requested through the enrollment profile. Only returned if an `allowed_hours_to` value is set for the profile. Format: `HH:MM:SS`\n", "format": "date", "example": "17:30:00" }, "timezone": { "type": "string", "description": "Region-based time zone ID for the `allowed_hours_from` and `allowed_hours_to` values. Only returned if a `timezone` value is set for the profile. Format: `Area/Location` (for example, `America/New_York`).\n", "example": "America/New_York" }, "valid_from": { "type": "string", "description": "Date the enrollment profile is valid from. Only returned if a `valid_from` date is set for the profile. Format: `YYYY-MM-DD`.\n", "example": "2021-06-25", "format": "date" }, "expires_on": { "type": "string", "description": "Date the enrollment profile expires. Only returned if an `expires_on` date is set for the profile. Format: `YYYY-MM-DD`.\n", "example": "2022-06-25", "format": "date" }, "key_generation_allow_to_change": { "type": "boolean", "description": "For certificate requests and batch enrollment jobs that use server-side keypair generation. If true, enrollment profile allows certificate requests to use any key type allowed in the certificate profile. Otherwise, the key type from the request is ignored, and the enrollment profile's default key type (`key_generation_type`) is used.\n", "example": true }, "key_generation_option": { "type": "string", "description": "Keypair generation option for certificate requests and batch enrollment jobs that use the enrollment profile.\n\nPossible values:\n\n- `client_side`: Enrollment profile only allows client-side keypair generation.\n- `server_side`: Enrollment profile only allows server-side keypair generation.\n- `client_or_server_side`: Enrollment profile allows both client-side and server-side keypair generation.\n", "enum": [ "client_side", "server_side", "client_or_server_side" ], "example": "client_or_server_side" }, "key_generation_type": { "type": "string", "description": "Default key type for server-side keypair generation.\n", "example": "RSA_2048", "enum": [ "RSA_2048", "RSA_3072", "RSA_4096", "P_256", "P_384", "P_512", "ED_25519" ] }, "allow_key_cache": { "type": "boolean", "description": "If true, when you request a certificate using server-side keypair generation, DigiCert IoT® Trust Manager caches the AES key that encrypts the returned keypair. Then, for the duration specified by `key_cache_validity_period`, the same key encrypts keypairs returned by subsequent certificate requests. When this encryption key expires, the system generates a new one, which is cached for reuse in the same way.\n\nIf false, DigiCert IoT® Trust Manager generates a unique encryption key for each certificate request.\n" }, "key_cache_validity_period_type": { "type": "string", "description": "Unit of time for the key cache validity period. Omitted if `allow_key_cache` is false.\n", "example": "days", "enum": [ "days", "hours", "minutes", "seconds" ] }, "key_cache_validity_period": { "type": "string", "description": "Key cache validity period. Omitted if `allow_key_cache` is false.\n" }, "require_approval_for_enroll": { "type": "boolean", "default": false, "description": "If true, a user with `APPROVE_IOT_CERTIFICATE` permissions must approve enrollment requests created with this enrollment profile. Otherwise, false (default).\n\nEnrollment requests pending approval appear in the list of requests in your account. DigiCert® IoT Trust Manager only issues the certificate when the request is approved.\n", "example": false }, "require_approval_for_renew": { "type": "boolean", "default": false, "description": "If true, a user with `APPROVE_IOT_CERTIFICATE` permissions must approve renewal requests created with this enrollment profile. Otherwise, false (default).\n\nRenewal requests pending approval appear in the list of requests in your account. DigiCert® IoT Trust Manager only issues the certificate when the request is approved.\n", "example": false }, "digest_email_notification_period": { "type": "string", "description": "Frequency of request notification emails for the enrollment profile.\n\nAllowed values:\n* `individual_request`: DigiCert® IoT Trust Manager sends an email each time a request is created.\n\n* `daily_digest`: DigiCert® IoT Trust Manager sends a daily email with the total number of pending requests.\n\n* `do_not_send`: DigiCert® IoT Trust Manager doesn't send notification emails.\n", "enum": [ "individual_request", "daily_digest", "do_not_send" ] }, "approvers": { "type": "array", "description": "List of objects with details about each user that receives request notification emails for the enrollment profile. If empty, all users with `APPROVE_IOT_CERTIFICATE` permissions receive request notification emails.\n", "items": { "type": "object", "description": "Approver user object.", "properties": { "id": { "description": "User ID.", "example": "4db36e5c-4bb8-4a41-a941-1b31a82529bd", "format": "UUID", "type": "string" }, "full_name": { "type": "string", "description": "User first and last name.", "example": "John Doe" }, "email": { "type": "string", "description": "User email address", "example": "john.doe@example.com" }, "active": { "type": "boolean", "description": "If true, user is active. Otherwise, false.", "example": true }, "user_type": { "type": "string", "description": "User type. Because service users cannot be approvers, objects in the `approvers` array always return a `user_type` value of `standard`.", "enum": [ "standard" ], "example": "standard" }, "locale": { "type": "string", "example": "en_US", "description": "User locale.", "enum": [ "zh_CN", "zh_TW", "en_US", "fr_FR", "de_DE", "it_IT", "ja_JP", "ko_KR", "pt_PT", "ru_RU", "es_ES" ] } } } }, "notification_email_list": { "type": "array", "description": "List of additional email addresses that receive request notifications. If empty, no additional email addresses receive request notifications.\n", "items": { "type": "string", "description": "Email address.", "example": "example.com" } }, "id": { "$ref": "#/components/schemas/enrollment_profile_id" }, "connector_url": { "type": "string", "description": "Base domain for DigiCert ONE instance where external enrollment profile exists. For example, `https://one.digicert.com`. Only returned if `enrollment_method` is `EXTERNAL_BATCH`.", "example": "https://one.digicert.com" }, "connector_type": { "type": "string", "description": "Method by which to authenticate to the external enrollment profile. Only returned if `enrollment_method` is `EXTERNAL_BATCH`. Possible values: `passcode`, `certificate`, `api_token`.\n", "enum": [ "passcode", "certificate", "api_token" ] }, "passcode": { "type": "string", "description": "Passcode for authenticating to external enrollment profile. Only returned if `connector_type` is `passcode`.\n", "example": "passcode" }, "api_key": { "type": "string", "description": "API token for authenticating to external enrollment profile. The token must belong to an admin or service user in the DigiCert ONE instance where the external enrollment profile resides. Only returned if `connector_type` is `api_token`.\n", "example": "" }, "auth_cert_pkcs12": { "type": "string", "description": "Base 64-encoded string containing authentication certificate data for authenticating to external enrollment profile. Only returned if `connector_type` is `certificate`.\n", "example": "" }, "auth_cert_password_pkcs12": { "type": "string", "description": "Passcode for authentication certificate (`auth_cert_pkcs12`). Only returned if `connector_type` is `certificate`.", "example": "passcode" }, "external_enrollment_profile_id": { "type": "string", "description": "ID of external enrollment profile. Only returned if `enrollment_method` is `EXTERNAL_BATCH`." }, "device_profile": { "type": "object", "description": "Object with device profile details.", "properties": { "id": { "type": "string", "description": "Device profile ID.", "example": "f5218cc5-fd11-47ac-bff8-0058f8e2d0ed" }, "name": { "type": "string", "description": "Device profile name.", "example": "Device profile name" } } }, "certificate_profile": { "type": "object", "description": "Object with certificate profile details.", "properties": { "id": { "type": "string", "description": "Certificate profile ID.", "example": "880daffe-e70f-4eb3-bfd5-673419cef80b" }, "name": { "type": "string", "description": "Certificate profile name.", "example": "Certificate profile name" } } }, "created_at": { "type": "string", "format": "date", "description": "Date and time the enrollment profile was created. Format: UTC timezone and ISO 8601 date (`YYYY-MM-DDThh:mm:ss.sTZD`)\n", "example": "2021-06-09T13:49:54Z" }, "ica": { "type": "object", "description": "Object with the name and ID of the intermediate ICA that issues certificates requested through the enrollment profile.", "properties": { "id": { "type": "string", "description": "ICA ID.", "example": "AAC2E2DD6BEAE2E5EE93954BAE15E34D" }, "name": { "type": "string", "description": "ICA name.", "example": "ICA Name" } } }, "status": { "type": "string", "description": "Enrollment profile status.", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "allowed_signature_algorithms": { "type": "array", "description": "List of signature algorithms allowed when requesting certificates using the enrollment profile.", "example": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA" ], "items": { "type": "string", "description": "Signature algorithm.", "enum": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA" ], "example": "sha384WithRSA" } }, "direct_mapping": { "type": "boolean", "description": "Always true. The `direct_mapping` field ensures backwards compatibility with an earlier version of enrollment profiles.", "example": true }, "account_id": { "type": "string", "description": "ID of account the enrollment profile belongs to.", "example": "742a7efb-0cf1-499d-abd5-abb87f42aa5f" }, "ca_body": { "example": "", "type": "string", "description": "Issuing intermediate CA certificate for x509 certificates requested using the enrollment profile. Format: base64-encoded string.\n" }, "gp_ca_body": { "example": "", "type": "string", "description": "Issuing intermediate CA certificate for Global Platform certificates requested using the enrollment profile. Only returned for enrollment profiles with Global Platform certificate support. Format: base64-encoded string.\n" }, "ca_chain": { "type": "array", "description": "List of objects containing the intermediate CA and root certificates from the certificate chain for x509 certificates. Each certificate in the `ca_chain` array is signed by the certificate in the object that follows it.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "cert_type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "blob": { "type": "string", "description": "Certificate blob.", "example": "" } } } }, "gp_ca_chain": { "type": "array", "description": "List of objects containing the intermediate CA and root certificates from the certificate chain for Global Platform certificates. Each certificate in the `ca_chain` array is signed by the certificate in the object that follows it. Only returned for enrollment profiles with Global Platform certificate support.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "cert_type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "blob": { "type": "string", "description": "Certificate blob.", "example": "" } } } }, "certificate_template": { "type": "object", "description": "Name and ID of certificate template associated with the enrollment profile.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Certificate template ID (UUID).", "example": "ebe32558-6485-4810-938b-56882daed038" }, "name": { "type": "string", "description": "Certificate template name.", "example": "Certificate Template Name" } } }, "scep_get_ca_cert_response_with_root": { "type": "boolean", "description": "Option to include root CA to GetCACert operation response. Only available for SCEP enrollment method.\n", "example": false }, "scep_get_ca_cert_response_der_format": { "type": "boolean", "description": "When set to true we force GetCACert operation response content type header to application/x-x509-ca-cert. Only available for SCEP enrollment method.\n", "example": false }, "scep_encryption_algorithm": { "type": "string", "description": "Encryption algorithm to use for response encryption. Default aes128WithCBC.\n", "example": "aes128WithCBC" } } }, "enrollmentProfileInList": { "description": "Object containing enrollment profile details.", "type": "object", "properties": { "name": { "type": "string", "description": "Enrollment profile name.", "example": "Example name" }, "enrollment_methods": { "type": "array", "description": "List of enrollment methods enabled for the profile.", "items": { "type": "string", "description": "Enrollment method.", "enum": [ "EST", "SCEP", "CMP_V2", "ACME", "API", "PORTAL", "CERTIFICATE_IMPORT", "BATCH", "EXTERNAL_BATCH" ] }, "example": [ "API", "PORTAL" ] }, "allowed_ip_addresses": { "type": "array", "description": "List of IP addresses allowed to request certificates using the enrollment profile.", "items": { "type": "string", "example": "1.1.1.1" }, "example": [ "1.1.1.1", "2.2.2.2" ] }, "allowed_hours_from": { "type": "string", "description": "Daily start time in the specified `timezone` (UTC if no `timezone` is set) for when certificates can be requested through the enrollment profile. Only returned if an `allowed_hours_from` value is set for the profile. Format: `HH:MM:SS`\n", "format": "date", "example": "09:45:00" }, "allowed_hours_to": { "type": "string", "description": "Daily end time in the specified `timezone` (UTC if no `timezone` is set) for when certificates can be requested through the enrollment profile. Only returned if an `allowed_hours_to` value is set for the profile. Format: `HH:MM:SS`\n", "format": "date", "example": "17:30:00" }, "timezone": { "type": "string", "description": "Region-based time zone ID for the `allowed_hours_from` and `allowed_hours_to` values. Only returned if a `timezone` value is set for the profile. Format: `Area/Location` (for example, `America/New_York`).\n", "example": "America/New_York" }, "valid_from": { "type": "string", "description": "Date the enrollment profile is valid from. Only returned if a `valid_from` date is set for the profile. Format: `YYYY-MM-DD`.\n", "example": "2021-06-25", "format": "date" }, "expires_on": { "type": "string", "description": "Date the enrollment profile expires. Only returned if an `expires_on` date is set for the profile. Format: `YYYY-MM-DD`.\n", "example": "2022-06-25", "format": "date" }, "key_generation_allow_to_change": { "type": "boolean", "description": "For certificate requests and batch enrollment jobs that use server-side keypair generation. If true, enrollment profile allows certificate requests to use any key type allowed in the certificate profile. Otherwise, the key type from the request is ignored, and the enrollment profile's default key type (`key_generation_type`) is used.\n", "example": true }, "key_generation_option": { "type": "string", "description": "Keypair generation option for certificate requests and batch enrollment jobs that use the enrollment profile.\n\nPossible values:\n\n- `client_side`: Enrollment profile only allows client-side keypair generation.\n- `server_side`: Enrollment profile only allows server-side keypair generation.\n- `client_or_server_side`: Enrollment profile allows both client-side and server-side keypair generation.\n", "enum": [ "client_side", "server_side", "client_or_server_side" ], "example": "client_or_server_side" }, "key_generation_type": { "type": "string", "description": "Default key type for server-side keypair generation.\n", "example": "RSA_2048", "enum": [ "RSA_2048", "RSA_3072", "RSA_4096", "P_256", "P_384", "P_512", "ED_25519" ] }, "allow_key_cache": { "type": "boolean", "description": "If true, when you request a certificate using server-side keypair generation, DigiCert IoT® Trust Manager caches the AES key that encrypts the returned keypair. Then, for the duration specified by `key_cache_validity_period`, the same key encrypts keypairs returned by subsequent certificate requests. When this encryption key expires, the system generates a new one, which is cached for reuse in the same way.\n\nIf false, DigiCert IoT® Trust Manager generates a unique encryption key for each certificate request.\n" }, "key_cache_validity_period_type": { "type": "string", "description": "Unit of time for the key cache validity period. Omitted if `allow_key_cache` is false.\n", "example": "days", "enum": [ "days", "hours", "minutes", "seconds" ] }, "key_cache_validity_period": { "type": "string", "description": "Key cache validity period. Omitted if `allow_key_cache` is false.\n" }, "require_approval_for_enroll": { "type": "boolean", "default": false, "description": "If true, a user with `APPROVE_IOT_CERTIFICATE` permissions must approve enrollment requests created with this enrollment profile. Otherwise, false (default).\n\nEnrollment requests pending approval appear in the list of requests in your account. DigiCert® IoT Trust Manager only issues the certificate when the request is approved.\n", "example": false }, "require_approval_for_renew": { "type": "boolean", "default": false, "description": "If true, a user with `APPROVE_IOT_CERTIFICATE` permissions must approve renewal requests created with this enrollment profile. Otherwise, false (default).\n\nRenewal requests pending approval appear in the list of requests in your account. DigiCert® IoT Trust Manager only issues the certificate when the request is approved.\n", "example": false }, "digest_email_notification_period": { "type": "string", "description": "Frequency of request notification emails for the enrollment profile.\n\nAllowed values:\n* `individual_request`: DigiCert® IoT Trust Manager sends an email each time a request is created.\n\n* `daily_digest`: DigiCert® IoT Trust Manager sends a daily email with the total number of pending requests.\n\n* `do_not_send`: DigiCert® IoT Trust Manager doesn't send notification emails.\n", "enum": [ "individual_request", "daily_digest", "do_not_send" ] }, "notification_email_list": { "type": "array", "description": "List of additional email addresses that receive request notifications. If empty, no additional email addresses receive request notifications.\n", "items": { "type": "string", "description": "Email address.", "example": "example.com" } }, "id": { "$ref": "#/components/schemas/enrollment_profile_id" }, "connector_url": { "type": "string", "description": "Base domain for DigiCert ONE instance where external enrollment profile exists. For example, `https://one.digicert.com`. Only returned if `enrollment_method` is `EXTERNAL_BATCH`.", "example": "https://one.digicert.com" }, "connector_type": { "type": "string", "description": "Method by which to authenticate to the external enrollment profile. Only returned if `enrollment_method` is `EXTERNAL_BATCH`. Possible values: `passcode`, `certificate`, `api_token`.\n", "enum": [ "passcode", "certificate", "api_token" ] }, "passcode": { "type": "string", "description": "Passcode for authenticating to external enrollment profile. Only returned if `connector_type` is `passcode`.\n", "example": "passcode" }, "api_key": { "type": "string", "description": "API token for authenticating to external enrollment profile. The token must belong to an admin or service user in the DigiCert ONE instance where the external enrollment profile resides. Only returned if `connector_type` is `api_token`.\n", "example": "" }, "auth_cert_pkcs12": { "type": "string", "description": "Base 64-encoded string containing authentication certificate data for authenticating to external enrollment profile. Only returned if `connector_type` is `certificate`.\n", "example": "" }, "auth_cert_password_pkcs12": { "type": "string", "description": "Passcode for authentication certificate (`auth_cert_pkcs12`). Only returned if `connector_type` is `certificate`.", "example": "passcode" }, "external_enrollment_profile_id": { "type": "string", "description": "ID of external enrollment profile. Only returned if `enrollment_method` is `EXTERNAL_BATCH`." }, "device_profile": { "type": "object", "description": "Object with device profile details.", "properties": { "id": { "type": "string", "description": "Device profile ID.", "example": "f5218cc5-fd11-47ac-bff8-0058f8e2d0ed" }, "name": { "type": "string", "description": "Device profile name.", "example": "Device profile name" } } }, "certificate_profile": { "type": "object", "description": "Object with certificate profile details.", "properties": { "id": { "type": "string", "description": "Certificate profile ID.", "example": "880daffe-e70f-4eb3-bfd5-673419cef80b" }, "name": { "type": "string", "description": "Certificate profile name.", "example": "Certificate profile name" } } }, "created_at": { "type": "string", "format": "date", "description": "Date and time the enrollment profile was created. Format: UTC timezone and ISO 8601 date (`YYYY-MM-DDThh:mm:ss.sTZD`)\n", "example": "2021-06-09T13:49:54Z" }, "ica": { "type": "object", "description": "Object with the name and ID of the intermediate ICA that issues certificates requested through the enrollment profile.", "properties": { "id": { "type": "string", "description": "ICA ID.", "example": "AAC2E2DD6BEAE2E5EE93954BAE15E34D" }, "name": { "type": "string", "description": "ICA name.", "example": "ICA Name" } } }, "status": { "type": "string", "description": "Enrollment profile status.", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "allowed_signature_algorithms": { "type": "array", "description": "List of signature algorithms allowed when requesting certificates using the enrollment profile.", "example": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA" ], "items": { "type": "string", "description": "Signature algorithm.", "enum": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA" ], "example": "sha384WithRSA" } }, "direct_mapping": { "type": "boolean", "description": "Always true. The `direct_mapping` field ensures backwards compatibility with an earlier version of enrollment profiles.", "example": true }, "account_id": { "type": "string", "description": "ID of account the enrollment profile belongs to.", "example": "742a7efb-0cf1-499d-abd5-abb87f42aa5f" }, "ca_body": { "example": "", "type": "string", "description": "Issuing intermediate CA certificate for x509 certificates requested using the enrollment profile. Format: base64-encoded string.\n" }, "gp_ca_body": { "example": "", "type": "string", "description": "Issuing intermediate CA certificate for Global Platform certificates requested using the enrollment profile. Only returned for enrollment profiles with Global Platform certificate support. Format: base64-encoded string.\n" }, "ca_chain": { "type": "array", "description": "List of objects containing the intermediate CA and root certificates from the certificate chain for x509 certificates. Each certificate in the `ca_chain` array is signed by the certificate in the object that follows it.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "cert_type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "blob": { "type": "string", "description": "Certificate blob.", "example": "" } } } }, "gp_ca_chain": { "type": "array", "description": "List of objects containing the intermediate CA and root certificates from the certificate chain for Global Platform certificates. Each certificate in the `ca_chain` array is signed by the certificate in the object that follows it. Only returned for enrollment profiles with Global Platform certificate support.", "items": { "type": "object", "description": "Object with certificate data.", "properties": { "cert_type": { "type": "string", "description": "Certificate type (root or intermediate).", "enum": [ "intermediate", "root" ], "example": "intermediate" }, "blob": { "type": "string", "description": "Certificate blob.", "example": "" } } } }, "certificate_template": { "type": "object", "description": "Name and ID of certificate template associated with the enrollment profile.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Certificate template ID (UUID).", "example": "ebe32558-6485-4810-938b-56882daed038" }, "name": { "type": "string", "description": "Certificate template name.", "example": "Certificate Template Name" } } }, "scep_get_ca_cert_response_with_root": { "type": "boolean", "description": "Option to include root CA to GetCACert operation response. Only available for SCEP enrollment method.\n", "example": false }, "scep_get_ca_cert_response_der_format": { "type": "boolean", "description": "When set to true we force GetCACert operation response content type header to application/x-x509-ca-cert. Only available for SCEP enrollment method.\n", "example": false }, "scep_encryption_algorithm": { "type": "string", "description": "Encryption algorithm to use for response encryption. Default aes128WithCBC.\n", "example": "aes128WithCBC" } } }, "icaDetails": { "type": "object", "properties": { "id": { "type": "string", "description": "ICA ID.", "example": "AAC2E2DD6BEAE2E5EE93954BAE15E34D" }, "common_name": { "type": "string", "description": "ICA common name.", "example": "Issuing ICA name" }, "organization_name": { "type": "string", "description": "ICA organization name.", "example": "ICA organization name" }, "serial_number": { "type": "string", "description": "ICA serial number.", "example": "3031D3B7E49697B5BFF95F972E8C917D5A2BDE4D" }, "status": { "type": "string", "description": "ICA status.", "enum": [ "active", "disabled" ], "example": "active" }, "valid_from": { "type": "string", "format": "date", "description": "Start date of the ICA validity period. Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2021-06-09T13:54:07Z" }, "valid_to": { "type": "string", "format": "date", "description": "End date of the ICA validity period. Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2051-06-09T13:06:23Z" } } }, "updateDeviceRequest": { "description": "Object with device details.", "type": "object", "properties": { "device_identifier": { "type": "string", "description": "Unique device name. Character limit: 255", "maxLength": 255, "example": "Device name" }, "fields": { "type": "array", "description": "Array of objects with key/value pairs for device fields. Whether a field is optional or required is defined in the device profile.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Existing field ID as defined in the device profile.", "example": "123c456e-789c-1e23-4567-ee90f39458fb" }, "value": { "type": "string", "description": "New field value.", "example": "Field value" } } } }, "device_api_allow_read": { "type": "boolean", "description": "If true, the device can read its own device information by submitting a request to the `GET /v2/device/{device_id}` or `GET /v3/device/{device_identifier}` endpoints. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true }, "device_api_allow_write": { "type": "boolean", "description": "If true, the device can update its own device information by submitting a request to the `PUT /v2/device/{device_id}` or `PUT /v3/device/{device_identifier}` endpoints. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true }, "device_api_allow_renew_certificate": { "type": "boolean", "description": "If true, the device can renew its own certificates by submitting a request to the `POST /v2/device/{device_id}/renew` or `POST /v3/device/{device_identifier}/renew` endpoints. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true }, "device_api_allow_revoke": { "type": "boolean", "description": "If true, the device can revoke its own certificates by submitting a request to the `POST /v2/device/{device_id}/revoke` or `POST /v3/device/{device_identifier}/revoke` endpoints. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true } } }, "revokeCertificateRequest": { "required": [ "reason" ], "type": "object", "properties": { "reason": { "description": "Reason for revocation.", "example": "key_compromise", "type": "string", "enum": [ "unspecified", "key_compromise", "affiliation_changed", "superseded", "cessation_of_operation", "certificate_hold", "privilege_withdrawn", "aa_compromise" ] }, "revocation_date": { "description": "Specific day the certificate is considered revoked. Should be after issuance date and before expiration date. Signing or other activities performed with the certificate before the revocation date are still considered valid. Format: UTC timezone and ISO 8601 date.\n\n**Default**: If not provided, revocation date is the date you submit the request.\n", "type": "string", "format": "date-time", "example": "2021-04-30T21:24:12Z" }, "comments": { "description": "User-entered notes.", "type": "string", "example": "Custom comment." } } }, "requestCertificateRequest": { "type": "object", "required": [ "csr", "enrollment_profile_id" ], "properties": { "csr": { "type": "string", "description": "Certificate signing request (CSR). Ignored in certificate requests using server-side keypair generation (`server_side_key_gen` = true).\n" }, "enrollment_profile_id": { "$ref": "#/components/schemas/enrollment_profile_id" }, "certificate_profile_attributes": { "type": "array", "items": { "$ref": "#/components/schemas/certificate_profile_attributes" }, "description": "List of one or more objects that set values for `user_provided` certificate attributes. The configuration of the certificate profile determines which certificate attributes are required in the certificate request.\n" }, "device_attributes": { "type": "array", "description": "List of one or more objects that set values for custom device attributes. Only attributes from the enrollment profile's \\\"Source fields\\\" are accepted.\n", "items": { "$ref": "#/components/schemas/device_attributes" } }, "response_with_certificate_only": { "type": "boolean", "description": "If true, returns end-entity certificate data instead of a JSON object. Otherwise, false (default). For X.509 certificates, returns the PEM-encoded data for the certificate body. For GlobalPlatform certificates, returns binary data for the certificate body.\n\nThis parameter is ignored if the enrollment profile requires approvals.\n", "example": false, "default": false }, "include_certificate_chain": { "type": "boolean", "description": "If true (default), response includes data for each certificate in the certificate chain (for example, end-entity certificate, intermediate CA certificate, and root certificate). If false, response includes data for the end-entity certificate only.\n\nThis parameter is ignored if the enrollment profile requires approvals.\n", "example": true, "default": true }, "split_certificate_response": { "type": "boolean", "description": "If true, each certificate in the certificate chain is returned in a separate field. The `pem` field contains the end-entity certificate, and the `chain` field contains a list of objects with intermediate CA and root certificate data. If false (default), the `pem` field contains the entire certificate chain, and no `chain` array is returned.\n\nThis parameter is ignored if the enrollment profile requires approvals.\n", "example": false, "default": false }, "server_side_key_gen": { "type": "boolean", "description": "If true, DigiCert® IoT Trust Manager generates the keypair for the certificate request (server-side keypair generation). The enrollment profile in the certificate request must allow server-side keypair generation. Any CSR in the request body is ignored. If false (default), the certificate request uses client-side keypair generation, and a CSR is required.\n", "example": false, "default": false }, "key_type": { "type": "string", "description": "Key type to use for server-side keypair generation. If not provided, DigiCert® IoT Trust Manager generates the key using the default key type set for the enrollment profile.\n\nAllowed key types are limited by the certificate profile associated with the enrollment profile in the request. This parameter is ignored if the key type for server-side keypair generation is fixed in the enrollment profile (`key_generation_allow_to_change` = false).\n", "enum": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ] }, "private_key_format": { "type": "string", "description": "Format of private key in response. Required if request uses server-side keypair generation; otherwise, ignored. Requests that use `cert_encrypted` or `cert_encrypted_key_only` must include an encryption certificate (`encryption_certificate`).\n\nPossible values:\n\n* `pem`: PEM format. If `response_with_certificate_only` is true, response content type is `application/x-pem-file`.\n* `pkcs_12`: PKCS12 format. Requests using this format must include a password (`pkcs12_password`) that will protect access to the PKCS12 file. If `response_with_certificate_only` is true, response content type is `application/x-pkcs12`.\n* `cert_encrypted`: Compressed archive (ZIP) containing private key, end-entity certificate, and certificate chain (if `include_certificate_chain` is true). DigiCert encrypts the ZIP file using the `encryption_certificate` you provide in your request. If `response_with_certificate_only` is true, response content type is `application/pkcs7-mime`.\n* `cert_encrypted_key_only`: Encrypted private key only. DigiCert encrypts the private key using the `encryption_certificate` you provide in your request.\n\nFor more information about private key formats, see [Request a certificate with server-side keypair generation](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/request-certificate-with-server-side-keypair-generation.html).\n\nThis parameter is ignored if the enrollment profile requires approvals.\n", "example": "pem", "enum": [ "pem", "pkcs_12", "cert_encrypted", "cert_encrypted_key_only" ] }, "pkcs12_password": { "type": "string", "description": "Password that protects the PKCS12 file containing the private key. Required if the value of the `private_key_format` parameter is `pkcs_12`; otherwise, ignored. Must be between 6-20 characters long. Allowed characters: A-Z, a-z, 0-9.\n\nThis parameter is ignored if the enrollment profile requires approvals.\n", "example": "p1w9r0d" }, "encryption_certificate": { "type": "string", "description": "End-entity certificate DigiCert® IoT Trust Manager uses to encrypt the private key. Required if the value of the `private_key_format` parameter is `cert_encrypted`; otherwise, ignored. Provide the certificate in PEM format as a single string with newline characters (`\\n`) between each new line. Include the header (`-----BEGIN CERTIFICATE-----`) and footer (`-----END CERTIFICATE-----`). Use this certificate to decrypt the returned private key.\n\nThis parameter is ignored if the enrollment profile requires approvals.\n", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" }, "request_id": { "$ref": "#/components/schemas/request_id" }, "note": { "$ref": "#/components/schemas/note" } } }, "renewCertificateRequest": { "description": "Request body for renewing a certificate.", "type": "object", "required": [], "properties": { "csr": { "type": "string", "description": "Certificate signing request (CSR). Ignored in certificate renewal requests using server-side keypair generation (`server_side_key_gen` = true).\n" }, "certificate_profile_attributes": { "type": "array", "items": { "$ref": "#/components/schemas/certificate_profile_attributes" }, "description": "List of one or more objects that set values for `user_provided` certificate attributes. The configuration of the certificate profile determines which certificate attributes are required in the certificate request.\n" }, "device_attributes": { "type": "array", "description": "List of one or more objects that set values for custom device attributes. Only attributes from the enrollment profile's \\\"Source fields\\\" are accepted.\n", "items": { "$ref": "#/components/schemas/device_attributes" } }, "response_with_certificate_only": { "type": "boolean", "description": "If true, returns end-entity certificate data instead of a JSON object. Otherwise, false (default). For X.509 certificates, returns the PEM-encoded data for the certificate body. For GlobalPlatform certificates, returns binary data for the certificate body.\n", "example": false, "default": false }, "server_side_key_gen": { "type": "boolean", "description": "If true, DigiCert® IoT Trust Manager generates the keypair for the certificate renewal request (server-side keypair generation). The enrollment profile used to issue the original certificate must allow server-side keypair generation. Any CSR in the request body is ignored. If false (default), the certificate request uses client-side keypair generation, and a CSR is required.\n", "example": false, "default": false }, "key_type": { "type": "string", "description": "Key type to use for server-side keypair generation. If not provided, DigiCert® IoT Trust Manager generates the key using the default key type set for the enrollment profile.\n\nAllowed key types are limited by the certificate profile associated with the enrollment profile used in the original certificate request. This parameter is ignored if the key type for server-side keypair generation is fixed in the enrollment profile (`key_generation_allow_to_change` = false).\n", "enum": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ] }, "private_key_format": { "type": "string", "description": "Format of private key in response. Required if request uses server-side keypair generation; otherwise, ignored.\n\nPossible values:\n\n* `pem`: PEM format. Content type for responses with certificate only is `application/x-pem-file`.\n* `pkcs_12`: PKCS12 format. Requests using this format must include a password (`pkcs12_password`) that will protect access to the PKCS12 file. Content type for response with certificate only is `application/x-pkcs12`.\n* `cert_encrypted`: Compressed archive (ZIP) encrypted with an end-entity certificate. Requests using this format must include an encryption certificate (`encryption_certificate`). Content type for response with certificate only is `application/pkcs7-mime`.\n\nFor more information about private key formats, see [Request a certificate with server-side keypair generation](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/request-certificate-with-server-side-keypair-generation.html).\n", "example": "pem", "enum": [ "pem", "cert_encrypted" ] }, "pkcs12_password": { "type": "string", "description": "Password that protects the PKCS12 file containing the private key. Required if the value of the `private_key_format` parameter is `pkcs_12`; otherwise, ignored. Must be between 6-20 characters long. Allowed characters: A-Z, a-z, 0-9.\n", "example": "p1w9r0d" }, "encryption_certificate": { "type": "string", "description": "End-entity certificate DigiCert® IoT Trust Manager uses to encrypt the private key. Required if the value of the `private_key_format` parameter is `cert_encrypted`; otherwise, ignored. Provide the certificate in PEM format as a single string with newline characters (`\\n`) between each new line. Include the header (`-----BEGIN CERTIFICATE-----`) and footer (`-----END CERTIFICATE-----`). Use this certificate to decrypt the returned private key.\n", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" }, "request_id": { "$ref": "#/components/schemas/request_id" }, "note": { "$ref": "#/components/schemas/note" } } }, "renewCertificateRequestByBody": { "description": "Request body for renewing a certificate.", "type": "object", "required": [ "certificate_to_renew" ], "properties": { "certificate_to_renew": { "type": "string", "description": "Body of certificate in PEM format to renew.\n", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" }, "csr": { "type": "string", "description": "Certificate signing request (CSR). Ignored in certificate renewal requests using server-side keypair generation (`server_side_key_gen` = true).\n" }, "certificate_profile_attributes": { "type": "array", "items": { "$ref": "#/components/schemas/certificate_profile_attributes" }, "description": "List of one or more objects that set values for `user_provided` certificate attributes. The configuration of the certificate profile determines which certificate attributes are required in the certificate request.\n" }, "device_attributes": { "type": "array", "description": "List of one or more objects that set values for custom device attributes. Only attributes from the enrollment profile's \\\"Source fields\\\" are accepted.\n", "items": { "$ref": "#/components/schemas/device_attributes" } }, "response_with_certificate_only": { "type": "boolean", "description": "If true, returns end-entity certificate data instead of a JSON object. Otherwise, false (default). For X.509 certificates, returns the PEM-encoded data for the certificate body. For GlobalPlatform certificates, returns binary data for the certificate body.\n", "example": false, "default": false }, "server_side_key_gen": { "type": "boolean", "description": "If true, DigiCert® IoT Trust Manager generates the keypair for the certificate renewal request (server-side keypair generation). The enrollment profile used to issue the original certificate must allow server-side keypair generation. Any CSR in the request body is ignored. If false (default), the certificate request uses client-side keypair generation, and a CSR is required.\n", "example": false, "default": false }, "key_type": { "type": "string", "description": "Key type to use for server-side keypair generation. If not provided, DigiCert® IoT Trust Manager generates the key using the default key type set for the enrollment profile.\n\nAllowed key types are limited by the certificate profile associated with the enrollment profile used in the original certificate request. This parameter is ignored if the key type for server-side keypair generation is fixed in the enrollment profile (`key_generation_allow_to_change` = false).\n", "enum": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ] }, "private_key_format": { "type": "string", "description": "Format of private key in response. Required if request uses server-side keypair generation; otherwise, ignored.\n\nPossible values:\n\n* `pem`: PEM format. Content type for responses with certificate only is `application/x-pem-file`.\n* `pkcs_12`: PKCS12 format. Requests using this format must include a password (`pkcs12_password`) that will protect access to the PKCS12 file. Content type for response with certificate only is `application/x-pkcs12`.\n* `cert_encrypted`: Compressed archive (ZIP) encrypted with an end-entity certificate. Requests using this format must include an encryption certificate (`encryption_certificate`). Content type for response with certificate only is `application/pkcs7-mime`.\n\nFor more information about private key formats, see [Request a certificate with server-side keypair generation](https://dev.digicert.com/en/digicert-one-apis/iot-device-manager-api/request-certificate-with-server-side-keypair-generation.html).\n", "example": "pem", "enum": [ "pem", "cert_encrypted" ] }, "pkcs12_password": { "type": "string", "description": "Password that protects the PKCS12 file containing the private key. Required if the value of the `private_key_format` parameter is `pkcs_12`; otherwise, ignored. Must be between 6-20 characters long. Allowed characters: A-Z, a-z, 0-9.\n", "example": "p1w9r0d" }, "encryption_certificate": { "type": "string", "description": "End-entity certificate DigiCert® IoT Trust Manager uses to encrypt the private key. Required if the value of the `private_key_format` parameter is `cert_encrypted`; otherwise, ignored. Provide the certificate in PEM format as a single string with newline characters (`\\n`) between each new line. Include the header (`-----BEGIN CERTIFICATE-----`) and footer (`-----END CERTIFICATE-----`). Use this certificate to decrypt the returned private key.\n", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" }, "request_id": { "$ref": "#/components/schemas/request_id" }, "note": { "$ref": "#/components/schemas/note" } } }, "revokeDeviceCertificateRequest": { "description": "Request body for revoking a certificate with device API.", "type": "object", "required": [ "reason" ], "properties": { "reason": { "description": "Reason for revocation.", "example": "key_compromise", "type": "string", "enum": [ "unspecified", "key_compromise", "affiliation_changed", "superseded", "cessation_of_operation", "certificate_hold", "privilege_withdrawn", "aa_compromise" ] }, "revocation_date": { "description": "Specific day the certificate is considered revoked. Should be after issuance date and before expiration date. Signing or other activities performed with the certificate before the revocation date are still considered valid. Format: UTC timezone and ISO 8601 date.\n\n**Default**: If not provided, revocation date is the date you submit the request.\n", "type": "string", "format": "date-time", "example": "2021-04-30T21:24:12Z" }, "comments": { "description": "User-entered notes.", "type": "string", "example": "Custom comment." }, "certificate_id": { "description": "Certificate ID to revoke.", "type": "string", "example": "66666666-7777-8888-9999-000000000000" }, "certificate_serial_number": { "type": "string", "description": "Serial number of the certificate to revoke.", "example": "4AEB02DBF882D9BEA9DB5E5D9F1E5E939B6B74D4" }, "certificate_thumbprint": { "type": "string", "description": "SHA256 thumbprint of the certificate to revoke.", "example": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143" }, "certificate_body": { "type": "string", "description": "PEM formatted certificate body.", "example": "-----BEGIN CERTIFICATE-----\nMIICrjCCAZagAwIBAgIUIm...\n-----END CERTIFICATE-----" } } }, "renewDeviceCertificateRequest": { "description": "Request body for renewing of certificate with device API.", "type": "object", "properties": { "csr": { "type": "string", "description": "Certificate signing request (CSR).\n" }, "certificate_profile_attributes": { "type": "array", "items": { "$ref": "#/components/schemas/certificate_profile_attributes" }, "description": "List of one or more objects that set values for `user_provided` certificate attributes. The configuration of the certificate profile determines which certificate attributes are required in the certificate request.\n" }, "device_attributes": { "type": "array", "description": "List of one or more objects that set values for custom device attributes. Only attributes from the enrollment profile's \\\"Source fields\\\" are accepted.\n", "items": { "$ref": "#/components/schemas/device_attributes" } }, "certificate_id": { "description": "Certificate ID to revoke.", "type": "string", "example": "66666666-7777-8888-9999-000000000000" }, "certificate_serial_number": { "type": "string", "description": "Serial number of the certificate to revoke.", "example": "4AEB02DBF882D9BEA9DB5E5D9F1E5E939B6B74D4" }, "certificate_thumbprint": { "type": "string", "description": "SHA256 thumbprint of the certificate to revoke.", "example": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143" }, "certificate_body": { "type": "string", "description": "PEM formatted certificate body.", "example": "-----BEGIN CERTIFICATE-----\nMIICrjCCAZagAwIBAgIUIm...\n-----END CERTIFICATE-----" } } }, "createEnrollmentPasscodeRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Given name for the passcode. Must be unique within the enrollment profile.", "maxLength": 64, "example": "Passcode name" }, "description": { "type": "string", "description": "Custom passcode description.", "maxLength": 255, "example": "Custom passcode description." }, "enable_username_for_passcode": { "type": "boolean", "example": true, "description": "If true, the option to add a username is enabled for the enrollment passcode. Otherwise, false (default). To associate a username with the enrollment passcode, the enrollment profile must use the EST or CMPv2 enrollment method.\n" }, "username": { "type": "string", "maxLength": 64, "example": "username_example", "description": "Enrollment passcode username. Username must have 1-64 characters and must be unique within the enrollment profile. The `username` parameter is required in requests with `enable_username_for_passcode` set to true. Otherwise, it is ignored.\n" }, "passcode_length": { "type": "integer", "description": "Number of characters in the passcode generated by DigiCert® IoT Trust Manager. **Note:** For enrollment profiles using the SCEP enrollment method, passcode length is fixed at 20 characters.\n", "maxLength": 64, "minLength": 20, "default": 27 }, "usage_limit": { "type": "integer", "description": "Number of times the passcode can be used. If not provided, the passcode does not have a usage limit.", "example": 100 }, "validity_period": { "type": "object", "description": "Object that defines the period of time during which the passcode can be used. If not provided, the passcode can be used immediately and does not expire.", "properties": { "from": { "type": "string", "description": "Start date of passcode validity period. If not provided, the passcode can be used immediately. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-01-01" }, "to": { "type": "string", "description": "End date of passcode validity period. If not provided, the passcode does not expire. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-06-01" } } }, "passcode": { "type": "string", "description": "User-provided passcode. Must be between 6 and 64 characters. If you do not provide a passcode, DigiCert® IoT Trust Manager generates the passcode for you.\n" }, "registered_values": { "type": "array", "description": "List of objects with details about the certificate fields to validate when using this passcode. If you don't need to validate certificate fields for this enrollment passcode, omit the `registered_values` object from your request.", "items": { "type": "object", "properties": { "certificate_field": { "type": "string", "description": "Name of a certificate field to validate when using this passcode.", "example": "subject.common_name", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "challenge_password" ] }, "matcher": { "type": "string", "description": "Operator used when comparing the value of the certificate field to the registered values.", "enum": [ "equals" ], "example": "equals" }, "value": { "description": "A value or list of values to compare with the value of the chosen `certificate_field`. Use a string to validate certificate fields that contain a string. Use an array to validate certificate fields that contain an array.", "oneOf": [ { "type": "string" }, { "type": "array", "items": {} } ] } } } } } }, "createDeviceRequest": { "description": "Object with device details.", "required": [ "division_id", "device_identifier", "device_profile_id" ], "properties": { "division_id": { "$ref": "#/components/schemas/division_id" }, "device_identifier": { "type": "string", "description": "Unique device name. Character limit: 255", "maxLength": 255, "example": "Device name" }, "device_profile_id": { "type": "string", "description": "ID of an existing device profile. The device profile is the template for the new device.", "example": "a81a431a-be7b-4f2e-8afd-b2778491511f" }, "fields": { "type": "array", "description": "Array of objects with key/value pairs for device fields. Whether a field is optional or required is defined in the device profile.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Existing field ID as defined in the device profile.", "example": "123c456e-789c-1e23-4567-ee90f39458fb" }, "value": { "type": "string", "description": "New field value.", "example": "Field value" } } } }, "device_api_allow_read": { "type": "boolean", "description": "If true, the device can read its own device information by submitting a request to the `GET /v2/device/{device_id}` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true }, "device_api_allow_write": { "type": "boolean", "description": "If true, the device can update its own device information by submitting a request to the `PUT /v2/device/{device_id}` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true }, "device_api_allow_renew_certificate": { "type": "boolean", "description": "If true, the device can renew its own certificates by submitting a request to the `PUT /v2/device/{device_id}/renew` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "default": true } } }, "updateAuthenticationCertificateRequest": { "type": "object", "description": "Request body for updating an authentication certificate.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Friendly name for the authentication certificate.", "example": "Example Name" }, "start_date": { "type": "string", "description": "Start date for the period of time during which the enrollment profile can use the authentication certificate. Can be earlier than the certificate’s \"valid from\" date. If not provided, there is no start date limitation. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-01-01" }, "end_date": { "type": "string", "description": "End date for the period of time during which the enrollment profile can use the authentication certificate. Can be later than the certificate’s \"valid to\" date. If not provided, there is no end date limitation. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-06-01" }, "usage_limit": { "type": "string", "description": "Number of times the authentication certificate can be used. If not provided, the authentication certificate does not have a usage limit.", "example": 0 }, "registered_values": { "type": "array", "items": { "$ref": "#/components/schemas/registered_value" } }, "update_passcode": { "type": "boolean", "default": false, "description": "If `true`, passcode configuration details in this request overwrite existing passcode configuration for the authentication certificate (`use_passcode`, `generation_option`, `passcode`, and `passcode_length`). Otherwise, passcode configuration remains unchanged.\n\n**Warning!** When `update_passcode` is `true`, this endpoint is destructive to passcode configuration fields. For requests that omit passcode configuration fields, default values are used.\n" }, "use_passcode": { "type": "boolean", "description": "If `true`, clients authenticating with these credentials must also provide a passcode in the `x-passcode` request header. Otherwise, no passcode is required.\n\n**Note:** This parameter must have a `true` value if the authentication CA template requires passcodes for authentication certificates (`\"force_passcode_for_auth_cert\" = \"true\"`.\n", "default": false }, "generation_option": { "type": "string", "description": "Passcode generation option. Required if `use_passcode` is `true`.\n\n* `AUTO`: DigiCert® IoT Trust Manager generates the passcode.\n* `PROVIDED`: Provide the passcode in your request.\n" }, "passcode": { "description": "Passcode. Must be between 6 and 64 characters. Required if `generate_option` is `PROVIDED`.", "minLength": 6, "maxLength": 64, "type": "string", "example": "ExamplePasscode123" }, "passcode_length": { "type": "integer", "description": "Number of characters in the passcode generated by DigiCert® IoT Trust Manager. Required if `generate_option` is `AUTO`.", "minLength": 20, "maxLength": 64, "example": 20 } } }, "batchEnrollmentJobResponse": { "type": "object", "description": "Object containing information about a batch enrollment job.", "properties": { "id": { "type": "string", "description": "Batch enrollment job ID.", "example": "da342f63-dead-4bae-a065-eb8822948148" }, "name": { "type": "string", "description": "Batch enrollment job friendly name.", "example": "Example batch job" }, "status": { "type": "string", "description": "Batch enrollment job status.\n\n- `PENDING`: Job submitted to processing queue.\n- `IN_PROGRESS`: Job is processing.\n- `PENDING_APPROVAL`: Job processed and ready to be approved or rejected.\n- `APPROVED`: Job approved and certificates are ready to be downloaded.\n- `REJECTED`: Job rejected.\n- `FAILED`: Job processing failed.\n", "enum": [ "PENDING", "IN_PROGRESS", "PENDING_APPROVAL", "APPROVED", "REJECTED", "FAILED" ] }, "total_items": { "type": "integer", "description": "Number of certificate requests in the batch enrollment job.", "example": 10 }, "failed_items": { "type": "integer", "description": "Number of failed certificate requests in the batch enrollment job.", "example": 0 }, "processing_time": { "type": "integer", "description": "Batch job processing time, in milliseconds.", "example": 900 }, "job_type": { "type": "string", "description": "Job type.", "example": "BATCH_CERTIFICATE_ENROLL", "enum": [ "BATCH_CERTIFICATE_ENROLL", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN", "BATCH_CERTIFICATE_ENROLL_WITH_KEY_GEN_MAC" ] }, "passcode": { "type": "string", "minLength": 6, "maxLength": 20, "description": "Passcode for external download link. Omitted if no passcode exists. **Note:** When the value of `passcode_generation_option` is `AUTO`, DigiCert® IoT Trust Manager only returns the full passcode once, when the passcode is created.\n", "example": "PA*******************" }, "passcode_generation_option": { "type": "string", "enum": [ "AUTO", "PROVIDED", "NONE" ], "description": "Generation method for passcode used to access external download link.\n\n* `NONE` (default): External recipients can download certificates without providing a passcode.\n* `AUTO`: DigiCert® IoT Trust Manager generates the passcode.\n* `PROVIDED`: A user provides the passcode.\n", "example": "AUTO" }, "description": { "type": "string", "description": "Custom description for the batch enrollment job. Omitted if no description exists.\n", "example": "Example description." }, "certificate_format": { "type": "string", "description": "File format of certificate output.\n", "enum": [ "PEM", "DER", "JSON" ], "example": "PEM" }, "emails": { "type": "array", "description": "Comma-separated list of email addresses for DigiCert ONE users who receive a notification email when the batch enrollment job is complete.", "items": { "type": "string" }, "example": [ "bob@example.com", "alice@example.com" ] }, "external_emails": { "type": "array", "description": "List of email addresses that receive a unique download link when the batch job is complete.\n", "example": [ "john@example.com", "jane@example.com" ], "items": { "type": "string" } }, "data_available": { "type": "boolean", "description": "If true, batch job results are available for download. Otherwise, false. **Note:** Batch job results remain available for 30 days after the job completes. You can still download individual certificates after the batch job itself is removed.\n" } } }, "deviceProfileResponse": { "type": "object", "description": "Object containing information about a device profile.", "properties": { "account_id": { "type": "string", "description": "ID of the account the device profile belongs to.", "example": "b29cc018-620e-4d4d-8488-c02e19e937b0" }, "division": { "$ref": "#/components/schemas/division" }, "id": { "type": "string", "description": "Device profile ID.", "example": "dcfe811c-ecf1-4d2e-bf44-462963bc4ade" }, "name": { "type": "string", "description": "Device profile name.", "example": "Example Device Profile" }, "description": { "type": "string", "description": "Custom device profile description.", "example": "Custom description" }, "status": { "type": "string", "description": "Device profile status.", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "fields": { "description": "List of objects defining custom fields for the device profile.", "type": "array", "items": { "type": "object", "description": "Object with information about a custom device field.", "properties": { "id": { "type": "string", "description": "Custom field ID.", "example": "5f5cd475-1e7d-4956-8a32-3fa29c56d8cf" }, "name": { "type": "string", "description": "Field name.", "example": "Optional custom field" }, "mandatory": { "type": "boolean", "description": "If true, the field is required when using this device profile to create a device. If false, the field is optional.\n", "example": false } } } }, "device_api_allow_read": { "type": "boolean", "description": "If true, devices using this profile can read their own device information by submitting a request to the `GET /v2/device/{device_id}` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.\n", "example": true }, "device_api_allow_renew_certificate": { "type": "boolean", "description": "If true, devices using this profile can renew their own certificates by submitting a request to the `PUT /v2/device/{device_id}/renew` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record.", "example": true }, "device_api_allow_revoke": { "type": "boolean", "description": "If true, devices using this profile can revoke their own certificates by submitting a request to the `PUT /v1/certificate/{certificate_id}/revoke` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record." }, "device_api_allow_write": { "type": "boolean", "description": "If true, devices using this profile can update their own device information by submitting a request to the `PUT /v2/device/{device_id}` endpoint. Otherwise, false. **Note:** Devices can use **client certificate authentication** to authenticate to the API with a certificate associated with their device record." } }, "example": { "id": "dcfe811c-ecf1-4d2e-bf44-462963bc4ade", "name": "Device profile example", "description": "An example device profile", "status": "ACTIVE", "device_api_allow_read": true, "device_api_allow_write": true, "device_api_allow_revoke": true, "device_api_allow_renew_certificate": true, "device_api_allow_enroll_certificate": false, "fields": [ { "id": "226ca489-1ce2-49ef-ab23-5968ae6440ef", "name": "mandatory", "mandatory": true }, { "id": "661820ce-4d8b-45bd-af2b-4baf924b8650", "name": "optional", "mandatory": false } ], "division": { "id": "d5faa1e-623a-47a9-831b-b9397c33395f", "name": "IoT Account" }, "account_id": "f92834ce-cdea-1584-b154-193bb198345e" } }, "managedCA": { "type": "object", "properties": { "id": { "type": "string", "description": "ICA ID.", "example": "01777FAA99199EFF90981078994EDD91" }, "common_name": { "type": "string", "description": "ICA common name.", "example": "Issuing ICA name" }, "organization": { "type": "string", "description": "ICA organization.", "example": "ICA organization name" }, "key_type": { "type": "string", "description": "ICA key type.", "example": "RSA 2048", "enum": [ "RSA 2048", "RSA 3072", "RSA 4096", "EC prime256v1", "EC prime384v1", "EC prime521v1", "ED25519" ] }, "signature_algorithm": { "type": "string", "description": "Signature algorithm used to sign ICA.", "example": "sha256WithRSA" }, "issuer_common_name": { "type": "string", "description": "Common name of the issuing certificate for the ICA.", "example": "Issuer common name" }, "body": { "type": "string", "description": "PEM-encoded ICA certificate data.", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n" }, "valid_from": { "type": "string", "format": "date", "description": "Start date of the ICA validity period (UTC). Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2021-06-09T13:54:07Z" }, "valid_to": { "type": "string", "format": "date", "description": "End date of the ICA validity period (UTC). Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2051-06-09T13:06:23Z" }, "serial_number": { "type": "string", "description": "ICA serial number.", "example": "" }, "thumbprint": { "type": "string", "description": "ICA's calculated sha256 thumbprint.", "example": "" }, "chain": { "$ref": "#/components/schemas/chain" } } }, "emails": { "type": "string", "description": "Comma-separated list of email addresses for users who receive a notification email when the batch enrollment job is complete.", "items": { "type": "string" }, "example": [ "bob@example.com", "alice@example.com" ] }, "description": { "type": "string", "maxLength": 1024, "description": "Custom description for the batch enrollment job. Character limit: 1024\n", "example": "Example description." }, "external_emails": { "type": "array", "description": "List of email addresses that receive a unique download link when the batch job is complete. Use this field to allow individuals without accounts to download the certificates.\n", "example": [ "john@example.com", "jane@example.com" ], "items": { "type": "string" } }, "passcode_generation_option": { "type": "string", "enum": [ "AUTO", "PROVIDED", "NONE" ], "description": "Generation method for passcode used to access external download link. Use this field to require a passcode from external recipients (`external_emails`) when downloading batch certificates.\n\n* `NONE` (default): External recipients can download certificates without providing a passcode.\n* `AUTO`: DigiCert® IoT Trust Manager generates a passcode for you.\n* `PROVIDED`: Provide your own passcode in the `passcode` request parameter.\n", "example": "AUTO" }, "passcode": { "type": "string", "minLength": 6, "maxLength": 20, "description": "Passcode for external download link. Must be between 6 and 20 characters. **Note:** When creating a new batch enrollment request, If `passcode_generation_option` is `PROVIDED` and you omit the `passcode` request parameter, DigiCert® IoT Trust Manager generates a passcode for you.\n" }, "certificateTemplateResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Certificate template ID (UUID).", "format": "uuid", "example": "2432c889-c2fc-4353-909a-a0ae1705451f" }, "name": { "type": "string", "description": "Unique name for the certificate template.", "example": "Example template" }, "created_at": { "type": "string", "description": "Date and time certificate template was created. Format: UTC timezone and ISO 8601 format.\n", "example": "2022-06-09T11:04:29Z" }, "body": { "$ref": "#/components/schemas/certificateTemplateBody" }, "status": { "type": "string", "description": "Certificate template status.", "example": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "type": { "type": "string", "description": "Certificate template type. A `custom` template can be used for certificate issuance. A `system` template can only be cloned.\n", "enum": [ "custom", "system" ] }, "limit_by_accounts": { "type": "boolean", "description": "If true, only certain accounts can use the certificate template. If false, access to the template is not limited to a list of accounts. Always true for custom certificate templates.\n" }, "accounts": { "type": "array", "description": "List of objects with the name and ID of each account that can use this template. Returns an empty array if `limit_by_accounts` is false.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Account name.", "example": "Example account" }, "id": { "type": "string", "description": "Account ID (UUID).", "example": "dc1e352e-08ab-4516-979d-6c0d398bfb39", "format": "uuid" } } } }, "format": { "type": "string", "description": "Certificate format.", "enum": [ "x509", "global-platform", "attribute-certificate" ], "example": "x509" }, "certificate_type": { "type": "string", "description": "Certificate type.", "enum": [ "end_entity", "intermediate" ] } }, "example": { "id": "5eda32f3-26e3-4c94-8826-4da221e0d7e8", "name": "Client Auth Example", "created_at": "2022-06-09T11:04:29Z", "body": { "key_types": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ], "issue_types": [ "client_authentication", "server_authentication" ], "signature_algorithm": { "allowed_algorithms": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA", "match_issuer" ], "default_algorithm": "match_issuer" }, "subject": { "attributes": [ { "type": "common_name", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "organization_name", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "organization_unit", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "street_address", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "postal_code", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "locality", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "state", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "country", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "email", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] } ] }, "extensions": { "key_usage": { "critical": true, "allow_critical_override": true, "required_usages": { "rsa": [ "digital_signature", "non_repudiation", "key_encipherment", "data_encipherment" ], "ecdsa": [ "digital_signature", "non_repudiation", "key_agreement" ] }, "optional_usages": { "rsa": [ "digital_signature", "non_repudiation", "key_encipherment", "data_encipherment" ], "ecdsa": [ "digital_signature", "non_repudiation", "key_agreement" ] } }, "extended_key_usage": { "critical": true, "allow_critical_override": true, "include": "optional", "required_usages": [ { "oid": "client_authentication", "name": "" } ], "optional_usages": [ { "oid": "server_authentication", "name": "" }, { "oid": "code_signing", "name": "" }, { "oid": "email_protection", "name": "" }, { "oid": "smart_card_logon", "name": "" } ] }, "san": { "critical": false, "dns_name": { "include": "no", "auto_include_cn": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, "user_principal_name": { "include": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, "email": { "include": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] } } }, "renewal_settings": { "renew_valid_cert": "anytime", "renew_expired_cert": "anytime", "renew_revoked_cert": true, "renewal_key_pair": "optional", "allow_override_renewal_key_pair": true }, "serial_number_size": 20, "validity": { "min_duration": { "value": 10, "unit": "DAYS" }, "max_duration": { "value": 5, "unit": "YEARS" }, "default_duration": { "min": { "value": 10, "unit": "DAYS" }, "max": { "value": 5, "unit": "YEARS" } } } }, "status": "ACTIVE", "type": "custom", "limit_by_accounts": true, "accounts": [ { "id": "bbd80931-6ae1-464c-9ba9-2f4a4ec63abb", "name": "IoT Account" } ], "format": "x509", "certificate_type": "end_entity" } }, "certificateTemplateBody": { "type": "object", "description": "Certificate template body, formatted as a JSON object.", "required": [ "key_types", "signature_algorithm", "subject", "extensions", "renewal_settings", "validity" ], "properties": { "key_types": { "type": "array", "description": "List of key types that can be used to generate a certificate.", "items": { "type": "string", "description": "Key type.", "enum": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_512", "ed_25519" ] }, "example": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_512", "ed_25519" ] }, "issue_types": { "type": "array", "description": "List of authentication types that certificates issued from this template can be used for.", "items": { "type": "string", "description": "Authentication type.", "enum": [ "client_authentication", "server_authentication", "private_smime" ] }, "example": [ "client_authentication", "server_authentication" ] }, "signature_algorithm": { "type": "object", "description": "Object with details about the template's allowed and default hash and signature algorithms.", "required": [ "allowed_algorithms", "default_algorithm" ], "properties": { "allowed_algorithms": { "type": "array", "description": "List of signature algorithms that can be used to sign certificates.", "items": { "type": "string", "description": "Signature algorithm.", "enum": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA", "match_issuer" ] }, "example": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA", "match_issuer" ] }, "default_algorithm": { "type": "string", "description": "Default signature algorithm.", "example": "match_issuer", "enum": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA", "match_issuer" ] } } }, "subject": { "type": "object", "description": "Object that defines the subject attributes and the order in which they appear in the certificate.", "required": [ "attributes" ], "properties": { "attributes": { "type": "array", "description": "List of attributes to include in the certificate.", "items": { "type": "object", "description": "Attribute object.", "required": [ "type", "allowed_source" ], "properties": { "type": { "type": "string", "description": "Type of attribute to include in the certificate.\n", "example": "common_name", "enum": [ "common_name", "country", "email", "locality", "organization_name", "organization_unit", "postal_code", "serial_number", "state", "street_address", "unique_identifier", "description", "domain_component", "unstructured_address", "unstructured_name", "dn_qualifier", "title", "given_name", "surname", "product_identifier", "vendor_identifier" ] }, "include": { "type": "string", "description": "If `yes` (default), the subject attribute value is required. If `optional`, the subject attribute value is optional.", "example": "optional", "enum": [ "yes", "optional" ] }, "encoding": { "type": "string", "description": "Encoding standard for the subject attribute value. Default: `auto`\n", "example": "auto", "enum": [ "auto", "utf8_string", "printable_string", "ia5_string" ] }, "allowed_source": { "$ref": "#/components/schemas/allowed_source" } } } }, "subject_order": { "type": "array", "description": "Ordered list that defines the order of the subject attributes in the certificate.", "example": [ "common_name", "country", "email", "locality", "organization_name", "organization_unit", "postal_code", "serial_number", "state", "street_address", "unique_identifier", "description", "domain_component", "unstructured_address", "unstructured_name", "dn_qualifier", "title", "given_name", "surname", "product_identifier", "vendor_identifier" ], "items": { "type": "string", "description": "Attribute name.", "enum": [ "common_name", "country", "email", "locality", "organization_name", "organization_unit", "postal_code", "serial_number", "state", "street_address", "unique_identifier", "description", "domain_component", "unstructured_address", "unstructured_name", "dn_qualifier", "title", "given_name", "surname", "product_identifier", "vendor_identifier" ] } } } }, "extensions": { "type": "object", "description": "Object that defines extensions to include in the certificate.", "required": [ "key_usage", "extended_key_usage" ], "properties": { "key_usage": { "type": "object", "description": "Defines key usage extension for the template. Note: If the template is for an intermediate CA certificate, the key usage extension is automatically set by DigiCert® CA Manager, and any value provided in the template is rejected.\n", "properties": { "critical": { "$ref": "#/components/schemas/critical" }, "allow_critical_override": { "type": "boolean", "description": "If true, the key usage critical setting can be changed in the certificate profile and certificate requests. If false (default), the key usage critical setting is always set according to the certificate template definition.", "example": false }, "required_usages": { "type": "object", "description": "List of required key usages to be included in the certificate.", "required": [ "rsa", "ecdsa" ], "properties": { "rsa": { "type": "array", "description": "List of required RSA key usages.", "items": { "type": "string", "enum": [ "digital_signature", "non_repudiation", "key_encipherment", "data_encipherment" ] } }, "ecdsa": { "type": "array", "description": "List of required ECDSA key usages. Note: ECDSA allows you to include only one of these in a certificate: `encipher_only` or `decipher_only`. You cannot include both of these key usages.\n", "items": { "type": "string", "enum": [ "digital_signature", "non_repudiation", "key_agreement", "encipher_only", "decipher_only" ] } } } }, "optional_usages": { "type": "object", "description": "List of optional key usages that can be included when selected in the certificate profile or provided in the certificate request.", "required": [ "rsa", "ecdsa" ], "properties": { "rsa": { "type": "array", "description": "List of optional RSA key usages that may be included if allowed in the certificate profile.", "items": { "type": "string", "enum": [ "digital_signature", "non_repudiation", "key_encipherment", "data_encipherment" ] } }, "ecdsa": { "type": "array", "description": "List of optional ECDSA key usages that may be included if allowed in the certificate profile. Note: ECDSA allows you to include only one of these in a certificate: `encipher_only` or `decipher_only`. You cannot include both of these key usages.\n", "items": { "type": "string", "enum": [ "digital_signature", "non_repudiation", "key_agreement", "encipher_only", "decipher_only" ] } } } } } }, "extended_key_usage": { "type": "object", "description": "Defines extended key usage extension for the template.", "properties": { "critical": { "$ref": "#/components/schemas/critical" }, "allow_critical_override": { "type": "boolean", "description": "If true, the extended key usage critical setting can be changed in the certificate profile and certificate requests. If false (default), the extended key usage critical setting is always set according to the certificate template definition.", "example": false }, "include": { "type": "string", "description": "If `yes` (default), the extended key usage extension will be included in the certificate. If `no`, the extended key usage extension will be excluded from the certificate.\n", "example": true, "enum": [ "yes", "no" ] }, "required_usages": { "type": "array", "description": "List of required extended key usages to be included in the certificate.", "items": { "type": "object", "properties": { "oid": { "type": "string", "enum": [ "client_authentication", "server_authentication", "code_signing", "email_protection", "smart_card_logon" ] }, "name": { "type": "string" } } } }, "optional_usages": { "type": "array", "description": "List of optional extended key usages that can be included when selected in the certificate profile or provided in the certificate request.", "items": { "type": "object", "properties": { "oid": { "type": "string", "enum": [ "client_authentication", "server_authentication", "code_signing", "email_protection", "smart_card_logon" ] }, "name": { "type": "string" } } } } } }, "san": { "type": "object", "description": "Defines subject alternative name (SAN) extension for the template.", "properties": { "critical": { "$ref": "#/components/schemas/critical" }, "dns_name": { "type": "object", "description": "DNS name details.", "required": [ "allowed_source" ], "properties": { "include": { "type": "string", "description": "Determines whether the SAN DNS name should be included in the certificate. Possible values:\n* `yes`: Include SAN DNS name in the certificate.\n* `optional`: If provided, include SAN DNS name in the certificate.\n* `no` (default): Do not include SAN DNS name in the certificate.\n", "enum": [ "yes", "no", "optional" ] }, "auto_include_cn": { "type": "string", "description": "Define if the common name is included and where it should be in the list of DNS names. Possible values:\n* `top` (default): Add common name as the first item in the DNS name list.\n* `bottom`: Add common name as the last item in the DNS name list.\n* `no`: Do not add the common name.\n", "enum": [ "top", "bottom", "no" ] }, "allowed_source": { "$ref": "#/components/schemas/allowed_source" } } }, "user_principle_name": { "type": "object", "description": "User principle name (UPN) details.", "required": [ "allowed_source" ], "properties": { "include": { "type": "string", "description": "Determines whether SAN UPN should be included in the certificate. Possible values:\n* `yes`: Include SAN UPN name in the certificate.\n* `optional`: If provided in the request, include SAN UPN in the certificate.\n* `no` (default): Do not include SAN UPN in the certificate.\n", "enum": [ "yes", "optional", "no" ] }, "allowed_source": { "$ref": "#/components/schemas/allowed_source" } } }, "email": { "type": "object", "description": "SAN email details.", "properties": { "include": { "type": "string", "description": "Determines whether SAN email should be included in the certificate. Possible values:\n* `yes`: Include SAN email in the certificate.\n* `optional`: If provided in the request, include SAN email in the certificate.\n* `no` (default): Do not include SAN email in the certificate.\n", "enum": [ "yes", "optional", "no" ] }, "allowed_source": { "$ref": "#/components/schemas/allowed_source" } } }, "uri": { "type": "object", "description": "SAN URI details.", "required": [ "allowed_source" ], "properties": { "include": { "type": "string", "description": "Determines whether SAN URI should be included in the certificate. Possible values:\n* `yes`: Include SAN URI in the certificate.\n* `optional`: If provided in the request, include SAN URI in the certificate.\n* `no` (default): Do not include SAN URI in the certificate.\n", "enum": [ "yes", "optional", "no" ] }, "allowed_source": { "$ref": "#/components/schemas/allowed_source" } } }, "registered_id": { "type": "object", "description": "SAN registered ID details.", "required": [ "allowed_source" ], "properties": { "include": { "type": "string", "description": "Determines whether SAN registered ID should be included in the certificate. Possible values:\n* `yes`: Include SAN registered ID in the certificate.\n* `optional`: If provided in the request, include SAN registered ID in the certificate.\n* `no` (default): Do not include SAN registered ID in the certificate.\n", "enum": [ "yes", "optional", "no" ] }, "allowed_source": { "$ref": "#/components/schemas/allowed_source" } } }, "other_name": { "type": "object", "description": "Other name details.", "properties": { "required_raw_types": { "type": "array", "description": "List of required OIDs that must be included in raw input. Required for raw other name value. Only use when you need to define raw other name.", "items": { "type": "string", "description": "OID that must be present in raw input." } }, "optional_raw_types": { "type": "array", "description": "List of optional OIDs that might be included in raw input. Only use when you need to define raw other name.", "items": { "type": "string", "description": "OID that might be present in raw input." } }, "required_types": { "type": "array", "description": "List of OIDs. Should include `hardware_module_name.type`. Required when you need to define hardware module name.", "items": { "type": "string" } }, "hardware_module_name": { "type": "object", "description": "Hardware module name details.", "properties": { "type": { "type": "string", "description": "OID." }, "serial_num": { "type": "string", "description": "Hex-encoded binary value." } } } } } } }, "certificate_policies": { "type": "object", "description": "Defines certificate policies extension for the template.", "properties": { "critical": { "$ref": "#/components/schemas/critical" }, "include": { "type": "string", "description": "Determines whether certificate policies should be included in the certificate. Possible values:\n* `yes`: Include certificate policies in the certificate.\n* `optional`: If provided, include certificate policies in the certificate.\n* `no`: Do not include certificate policies in the certificate.\n* `default`: Use the \"include\" setting from the intermediate certificate authority (CA) certificate.\n", "enum": [ "yes", "optional", "no", "default" ] }, "source": { "type": "array", "description": "List of allowed sources for the `certificate_policies` value.\n\nCan include one or more of these values listed in priority order, where `request` is the highest and `ca_config` is the lowest:\n1. `request`: Use the values provided in the certificate request.\n1. `template`: Use the fixed values provided in the certificate template (see `value` parameter below).\n1. `issuer`: Use the values from the issuing certificate authority (CA) certificate (intermediate CA or root CA).\n1. `ca_config`: Use the values from the intermediate CA certificate configuration.\n\n**Note:** If more than one source is specified and each source provides values, then only the values from the source with the highest priority will be used. For example, if `request` and `template` are listed, and both have values, the values from `request` will be used since it has the higher priority.\n", "items": { "type": "string", "description": "Source type.", "enum": [ "request", "issuer", "template", "ca_config" ] } }, "value": { "type": "object", "description": "List of certificate policy values that may be included in the certificate if `source` is set to `template`.", "required": [ "oid" ], "properties": { "oid": { "$ref": "#/components/schemas/certificate_policy_oid" }, "cps_uri": { "$ref": "#/components/schemas/cps_uri" }, "user_notice": { "$ref": "#/components/schemas/user_notice" } } }, "required": { "type": "object", "description": "List of certificate policy values to always include in the certificate, regardless of `source` type.", "required": [ "oid" ], "properties": { "oid": { "$ref": "#/components/schemas/certificate_policy_oid" }, "cps_uri": { "$ref": "#/components/schemas/cps_uri" }, "user_notice": { "$ref": "#/components/schemas/user_notice" } } }, "optional": { "type": "object", "description": "List of certificate policy values that can be used if the `source` type is `request`.\n\n* If the list is empty and the `source` type is `request`, then any policy can be passed.\n* If the `source` type is `request` and this list has any entries, then the requested policies OIDs must be in this list.\n\nThe URI and Notice come from the certificate template's `optional` list and not the `request`. This means the `request` only indicates which policies to include but does not define the policies.\n", "required": [ "oid" ], "properties": { "oid": { "$ref": "#/components/schemas/certificate_policy_oid" }, "cps_uri": { "$ref": "#/components/schemas/cps_uri" }, "user_notice": { "$ref": "#/components/schemas/user_notice" } } } } }, "subject_directory_attribute": { "type": "object", "description": "Defines subject directory attribute extension.", "properties": { "include": { "type": "string", "description": "Determines whether the subject directory attribute should be included in the certificate. Possible values:\n* `yes`: Include subject directory attribute in the certificate.\n* `optional`: If provided, include the subject directory attribute in the certificate.\n* `no` (default): Do not include subject directory attribute in the certificate.\n", "enum": [ "yes", "optional", "no" ] }, "allow_encoded_ext_value": { "type": "boolean", "description": "If true, allow encoded subject attribute directory. Omit if false; IoT only supports a value of true for the `allow_encoded_ext_value` field." } } }, "ski_extension": { "type": "object", "description": "Defines subject key identifier (SKI) extension.", "properties": { "include": { "type": "string", "description": "Determines whether the SKI extension should be included in the certificate. Possible values:\n* `yes` (default): Include SKI extension in the certificate.\n* `no`: Do not include SKI extension in the certificate.\n" }, "default_method": { "type": "string", "description": "Any value from the list of allowed methods." }, "allowed_methods": { "type": "array", "description": "List of allowed methods.", "items": { "type": "string", "enum": [ "method1", "method2" ] } } } }, "basic_constraints": { "type": "object", "description": "Defines basic constraints extension for the template.", "properties": { "include": { "type": "string", "description": "Determines whether the certificate includes the basic constraints extension. Possible values:\n* `yes` (default): Include basic constraints extension in certificates.\n* `no`: Do not include basic constraints extension in certificates.\n", "enum": [ "yes", "no" ] }, "ca": { "type": "boolean", "description": "If false (default), the certificate is not a certificate authority (CA) certificate. If true, the certificate is a CA certificate.\n\nFor intermediate CA certificate templates:\n* Set the value of the `ca` parameter to true.\n* The `key_usage` extension is set by DigiCert® CA Manager, and the certificate template must not include any `key_usage` values. Any `key_usage` value included in the certificate template will cause the certificate template to be rejected.\n" }, "path_length": { "type": "number", "description": "Sets the value of `pathLenConstraint` in the `basic_constraints` extension. This value describes the number of intermediate certificates that may follow a CA certificate in the certificate chain. This value is only used in templates for intermediate CA certificates. If the template is for end-entity certificates (`ca` is omitted or false), the `path_length` property is ignored.\n\nPossible values:\n* `0` (default): Include path length in the certificate and set its value to zero. CA certificates with a path length of 0 can only issue end-entity certificates.\n* `-1`: Exclude the field from the certificate and do not set path length.\n* `> 0`: Include the field in the certificate and set the path length to an integer greater than 0.\n" } } } } }, "renewal_settings": { "type": "object", "description": "Object that defines conditions for certificate renewal.", "properties": { "renew_valid_cert": { "type": "string", "description": "Define if and when a valid certificate can be renewed before it expires. Possible values:\n* `anytime`: Certificates can be renewed any time before expiration.\n* `in_specific_window` (default): Certificates can be renewed before they expire, but only once the renewal window begins. To define the renewal window, use `renew_before_expiration_window`.\n* `dont_allow`: Certificates that are not expired cannot be renewed.\n", "enum": [ "anytime", "in_specific_window", "down_allow" ] }, "renew_before_expiration_window": { "type": "object", "description": "Object that determines renewal window before the certificate expires. Required if `renew_valid_cert` is `in_specific_window`.", "required": [ "period", "duration" ], "properties": { "period": { "type": "string", "description": "Renewal window duration unit.\n", "enum": [ "minutes", "hours", "days", "months", "years" ] }, "duration": { "type": "number", "description": "Renewal window duration. Accepts any positive integer." } } }, "renew_expired_cert": { "type": "string", "description": "Define if and when an expired certificate can be renewed. Possible values:\n* `anytime`: Certificates can be renewed any time after expiration.\n* `in_specific_window` (default): Certificates can be renewed after they expire, but only during the renewal window. To define the renewal window, use `renew_after_expiration_window`.\n* `dont_allow`: Expired certificates cannot be renewed.\n", "enum": [ "anytime", "in_specific_window", "down_allow" ] }, "renew_after_expiration_window": { "type": "object", "description": "Object that determines renewal window after the certificate expires. Required if `renew_expired_cert` is `in_specific_window`.", "required": [ "period", "duration" ], "properties": { "period": { "type": "string", "description": "Renewal window duration unit.\n", "enum": [ "minutes", "hours", "days", "months", "years" ] }, "duration": { "type": "number", "description": "Renewal window duration. Accepts any positive integer." } } }, "renew_revoked_cert": { "type": "boolean", "description": "If true (default), revoked certificates can be renewed. If false, revoked certificates cannot be renewed." }, "renewal_key_pair": { "type": "string", "description": "Determines whether renewing a certificate uses the same keypair or a new keypair. Possible values:\n* `optional` (default): Same or new keypair can be used when renewing a certificate.\n* `always`: New keypair should be used when renewing a certificate.\n* `never`: Same keypair should be used when the renewing a certificate\n" }, "allow_override_renewal_key_pair": { "type": "boolean", "description": "If true (default), a certificate profile using the template can override the `renewal_key_pair` configuration. If false, certificate profiles cannot override the `renewal_key_pair` configuration." } } }, "serial_number_size": { "type": "number", "description": "Length of certificate serial number.\n", "default": 20, "minimum": 16, "maximum": 20 }, "validity": { "type": "object", "description": "Certificate validity details.", "properties": { "min_duration": { "description": "Details about minimum certificate validity. Required in templates that define a validity range.", "required": [ "value", "unit" ], "properties": { "value": { "type": "number", "description": "Minimum certificate validity duration. Accepts any positive integer." }, "unit": { "type": "string", "description": "Duration unit for minimum certificate validity.", "enum": [ "minutes", "hours", "days", "months", "years" ] } } }, "max_duration": { "description": "Details about maximum certificate validity. Required in templates that define a validity range.", "required": [ "value", "unit" ], "properties": { "value": { "type": "number", "description": "Maximum certificate validity duration. Accepts any positive integer." }, "unit": { "type": "string", "description": "Duration unit for maximum certificate validity.", "enum": [ "minutes", "hours", "days", "months", "years" ] } } }, "expiration_date": { "type": "object", "description": "Details about certificate validity expiration date. Required in templates that use an expiration date to define certificate validity.", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "Date certificate validity ends. Supported formats:\n* date (`YYYY-MM-DD`): In this case, time is always 00:00:00 UTC. Example: `2025-03-24`.\n* date and time (`YYYY-MM-DDTHH:mm:ssZ`). Example: `2025-03-24T14:00:00Z`\n" } } } } } } }, "createCertificateTemplateRequest": { "type": "object", "required": [ "name", "body", "accounts" ], "properties": { "name": { "type": "string", "description": "Unique name for the certificate template.", "example": "Example template" }, "body": { "$ref": "#/components/schemas/certificateTemplateBody" }, "type": { "type": "string", "description": "Certificate template type. A `custom` template can be used for certificate issuance. A `system` template can only be cloned.\n", "enum": [ "custom", "system" ] }, "accounts": { "type": "array", "description": "List account IDs for each account that can use this template.", "items": { "type": "string", "description": "Account ID (UUID).", "example": "dc1e352e-08ab-4516-979d-6c0d398bfb39", "format": "uuid" } }, "format": { "type": "string", "description": "Certificate format.", "default": "x509", "enum": [ "x509", "global-platform", "attribute-certificate" ], "example": "x509" }, "certificate_type": { "type": "string", "default": "end_entity", "description": "Certificate type.", "enum": [ "end_entity", "intermediate" ] } }, "example": { "name": "New template", "body": { "issue_types": [ "server_authentication", "client_authentication" ], "cert_type": "end_entity", "signature_algorithm": { "allowed_algorithms": [ "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "match_issuer" ], "default_algorithm": "match_issuer" }, "subject": { "attributes": [ { "type": "common_name", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "organization_name", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "organization_unit", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "street_address", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "postal_code", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "locality", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "state", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "country", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] }, { "type": "email", "include": "optional", "encoding": "auto", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] } ] }, "extensions": { "key_usage": { "critical": true, "allow_critical_override": true, "required_usages": { "rsa": [ "digital_signature", "key_encipherment" ], "ecdsa": [ "digital_signature", "key_agreement" ] }, "optional_usages": { "rsa": [ "digital_signature", "key_encipherment" ], "ecdsa": [ "digital_signature", "key_agreement" ] } }, "extended_key_usage": { "critical": true, "allow_critical_override": true, "required_usages": [ { "oid": "server_authentication", "name": "" }, { "oid": "client_authentication", "name": "" } ] }, "san": { "critical": false, "dns_name": { "include": "no", "auto_include_cn": "no", "allowed_source": [ "csr", "fixed_value", "user_supplied" ] } } }, "renewal_settings": { "renew_valid_cert": "anytime", "renew_expired_cert": "anytime", "renew_revoked_cert": true, "renewal_key_pair": "optional", "allow_override_renewal_key_pair": true }, "serial_number_size": 20, "validity": { "min_duration": { "value": 1, "unit": "days" }, "max_duration": { "value": 10, "unit": "years" }, "default_duration": { "min": { "value": 1, "unit": "days" }, "max": { "value": 10, "unit": "years" } } } }, "type": "custom", "accounts": [ "bbd80931-6ae1-464c-9ba9-2f4a4ec63abb" ], "format": "x509", "certificate_type": "end_entity" } }, "allowed_source": { "type": "array", "description": "List of allowed value sources.\n", "items": { "type": "string", "description": "Value source. Possible values:\n* `csr`: Sourced from CSR.\n* `user_supplied`: Provided in the certificate request. Only applies to the `API`, `PORTAL`, and `BATCH` enrollment methods.\n* `fixed_value` (default): Defined in the certificate profile. The fixed value is used when no `csr` or `user_supplied` value is provided.\n", "enum": [ "csr", "user_supplied", "fixed_value" ] } }, "critical": { "type": "boolean", "description": "If true, the extension is critical. If false (default), the extension is not critical." }, "certificate_policy_oid": { "description": "Policy OID.", "type": "string" }, "cps_uri": { "description": "URI to access the CPS statement.", "type": "string" }, "user_notice": { "description": "User notice/", "type": "string" }, "certificateProfileResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Certificate profile ID (UUID).", "format": "uuid", "example": "c8b030ca-1e2d-4189-bbee-21cc561f6c8e" }, "name": { "type": "string", "description": "Unique certificate profile name.", "example": "Example certificate profile" }, "account_id": { "type": "string", "description": "ID of the account the profile belongs to (UUID).", "format": "uuid", "example": "490e13ab-0a2f-4a9d-b52b-6942ea00588f" }, "certificate_template": { "type": "object", "description": "Name and ID of certificate template used in the certificate profile.", "properties": { "id": { "type": "string", "description": "Certificate template ID (UUID).", "example": "c4e3cf2a-8c4d-4145-be5f-a81140cfbf12" }, "name": { "type": "string", "description": "Certificate template name.", "example": "Certificate template example" } } }, "allow_bare_public_key": { "type": "boolean", "description": "If true, the certificate profile allows certificate issuance using a public key. If false, certificate requests must include a certificate signing request (CSR)." }, "created_at": { "type": "string", "description": "Date and time the certificate profile was created. Format: UTC timezone and ISO 8601 format.\n", "example": "2022-07-27T14:17:45Z", "format": "date-time" }, "status": { "type": "string", "description": "Certificate profile status.", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "body": { "type": "array", "description": "List of objects that configures certificate fields for the certificate profile.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Certificate field key.", "enum": [ "csr", "certificate_value", "unique_certificate_value", "signature_algorithm", "allow_any_key_type", "allowed_key_types", "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.street_address", "subject.postal_code", "subject.locality", "subject.state", "subject.country", "subject.email", "subject.unique_identifier", "validity.duration_unit", "validity.duration_value", "key_usage.critical", "extended_key_usage.critical", "extended_key_usage.additional_values", "renewal_settings.renew_valid_cert", "renewal_settings.renew_expired_cert", "renewal_settings.renew_revoked_cert", "renewal_settings.renewal_key_pair" ] }, "optional": { "type": "boolean", "description": "If true, the field is optional. If false, the field is required." }, "sources": { "type": "array", "description": "List of value sources for the field.", "items": { "type": "string", "description": "Source.", "enum": [ "csr", "fixed_value", "user_supplied" ] } }, "value": { "type": "string", "description": "Default field value." }, "enabled": { "type": "boolean", "description": "If true, the field is enabled. Otherwise, false." } } } }, "certificate_format": { "type": "string", "description": "Certificate format. Certificate profiles inherit certificate format from their certificate template.", "enum": [ "x509", "global-platform", "attribute-certificate" ] }, "certificate_type": { "type": "string", "description": "Certificate type. Certificate profiles inherit certificate type from their certificate template." }, "ca_connector_type": { "type": "string", "description": "CA connector type. Possible values: `digicert_one` (DigiCert® Account Manager) or `digicert_cis` (CertCentral CIS API).\n", "enum": [ "digicert_one", "digicert_cis" ] }, "divisions": { "type": "array", "description": "List of divisions assigned to the certificate profile.", "items": { "$ref": "#/components/schemas/division" } } }, "example": { "id": "1fb93940-7580-4f94-a8ca-57585f9ecb2e", "name": "Certificate profile example", "account_id": "5220789d-df09-485f-aa21-d2979188b3ca", "certificate_template": { "id": "c376def4-b39a-4301-8391-6ffecd071057", "name": "Certificate template example" }, "allow_bare_public_key": false, "created_at": "2022-07-06T08:22:25Z", "status": "ACTIVE", "body": [ { "key": "certificate_value", "optional": false, "sources": [ "fixed_value" ], "value": "auto", "enabled": true }, { "key": "unique_certificate_value", "optional": false, "sources": [ "fixed_value" ], "value": "no", "enabled": true }, { "key": "signature_algorithm", "optional": false, "sources": [ "fixed_value" ], "value": "match_issuer", "enabled": true }, { "key": "allow_any_key_type", "optional": false, "sources": [ "fixed_value" ], "value": "yes", "enabled": true }, { "key": "allowed_key_types", "optional": false, "sources": [ "fixed_value" ], "value": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ], "enabled": true }, { "key": "subject.common_name", "optional": false, "sources": [ "user_supplied", "csr" ], "enabled": true }, { "key": "subject.organization_name", "optional": true, "sources": [ "user_supplied", "csr" ], "enabled": true }, { "key": "subject.organization_unit", "optional": true, "sources": [], "enabled": false }, { "key": "subject.street_address", "optional": true, "sources": [], "enabled": false }, { "key": "subject.postal_code", "optional": true, "sources": [], "enabled": false }, { "key": "subject.locality", "optional": true, "sources": [], "enabled": false }, { "key": "subject.state", "optional": true, "sources": [], "enabled": false }, { "key": "subject.country", "optional": true, "sources": [], "enabled": false }, { "key": "subject.unique_identifier", "optional": true, "sources": [ "user_supplied", "csr" ], "enabled": true }, { "key": "validity.duration_unit", "optional": false, "sources": [ "fixed_value" ], "value": "months", "enabled": true }, { "key": "validity.duration_value", "optional": false, "sources": [ "fixed_value" ], "value": 9, "enabled": true }, { "key": "key_usage.critical", "optional": true, "sources": [ "fixed_value" ], "value": "yes", "enabled": false }, { "key": "extended_key_usage.critical", "optional": true, "sources": [ "fixed_value" ], "value": "yes", "enabled": false }, { "key": "extended_key_usage.additional_values", "optional": true, "sources": [], "enabled": false }, { "key": "renewal_settings.renew_valid_cert", "optional": false, "sources": [ "fixed_value" ], "value": "anytime", "enabled": true }, { "key": "renewal_settings.renew_expired_cert", "optional": false, "sources": [ "fixed_value" ], "value": "anytime", "enabled": true }, { "key": "renewal_settings.renew_revoked_cert", "optional": false, "sources": [ "fixed_value" ], "value": true, "enabled": true }, { "key": "renewal_settings.renewal_key_pair", "optional": false, "sources": [ "fixed_value" ], "value": "optional", "enabled": true } ], "enrollment_methods": [], "certificate_format": "x509", "certificate_type": "end_entity", "ca_connector_type": "digicert_one", "divisions": [ { "id": "4340c299-f39c-4fcf-8d3a-650d24e5eb99", "name": "Example division" } ] } }, "createCertificateProfileRequest": { "type": "object", "required": [ "account_id", "certificate_template_id", "name", "body" ], "properties": { "account_id": { "type": "string", "format": "uuid", "description": "ID of the account the certificate profile is for (UUID).", "example": "490e13ab-0a2f-4a9d-b52b-6942ea00588f" }, "certificate_template_id": { "type": "string", "format": "uuid", "description": "ID of the certificate template to use in the certificate profile.", "example": "c4e3cf2a-8c4d-4145-be5f-a81140cfbf12" }, "name": { "type": "string", "description": "Unique certificate profile name.", "example": "Example certificate profile" }, "body": { "type": "array", "description": "List of objects that configures certificate fields for the certificate profile.", "items": { "type": "object", "required": [ "key", "optional", "enabled", "sources", "value" ], "properties": { "key": { "type": "string", "description": "Certificate field key.", "enum": [ "csr", "certificate_value", "unique_certificate_value", "signature_algorithm", "allow_any_key_type", "allowed_key_types", "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.street_address", "subject.postal_code", "subject.locality", "subject.state", "subject.country", "subject.email", "subject.unique_identifier", "validity.duration_unit", "validity.duration_value", "key_usage.critical", "extended_key_usage.critical", "extended_key_usage.additional_values", "renewal_settings.renew_valid_cert", "renewal_settings.renew_expired_cert", "renewal_settings.renew_revoked_cert", "renewal_settings.renewal_key_pair" ] }, "optional": { "type": "boolean", "description": "If true, the field is optional. If false, the field is required." }, "sources": { "type": "array", "description": "List of value sources for the field.", "items": { "type": "string", "description": "Source.", "enum": [ "csr", "fixed_value", "user_supplied" ] } }, "value": { "type": "string", "description": "Default field value." }, "enabled": { "type": "boolean", "description": "If true, the field is enabled. Otherwise, false." } } } }, "divisions": { "type": "array", "description": "List of IDs for each division to assign to the certificate profile.", "items": { "$ref": "#/components/schemas/division_id" } } }, "example": { "account_id": "1fb93940-7580-4f94-a8ca-57585f9ecb2e", "certificate_template_id": "c376def4-b39a-4301-8391-6ffecd071057", "name": "New certificate profile", "body": [ { "key": "csr", "optional": false, "enabled": true, "sources": [ "user_supplied" ], "value": "" }, { "key": "certificate_value", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "auto" }, { "key": "unique_certificate_value", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "no" }, { "key": "signature_algorithm", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "match_issuer" }, { "key": "allow_any_key_type", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "yes" }, { "key": "allowed_key_types", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ] }, { "key": "subject.common_name", "optional": false, "enabled": true, "sources": [ "user_supplied", "csr" ], "value": "" }, { "key": "subject.organization_name", "optional": true, "enabled": true, "sources": [ "user_supplied", "csr" ], "value": "" }, { "key": "subject.organization_unit", "optional": true, "enabled": false, "sources": [], "value": [] }, { "key": "subject.street_address", "optional": true, "enabled": false, "sources": [], "value": [] }, { "key": "subject.postal_code", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "subject.locality", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "subject.state", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "subject.country", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "subject.email", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "validity.duration_unit", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "months" }, { "key": "validity.duration_value", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": 9 }, { "key": "key_usage.critical", "optional": true, "enabled": false, "sources": [ "fixed_value" ], "value": "yes" }, { "key": "extended_key_usage.critical", "optional": true, "enabled": false, "sources": [ "fixed_value" ], "value": "yes" }, { "key": "extended_key_usage.additional_values", "optional": true, "enabled": false, "sources": [], "value": [] }, { "optional": false, "enabled": true, "sources": [ "fixed_value" ], "key": "renewal_settings.renew_valid_cert", "value": "anytime" }, { "optional": false, "enabled": true, "sources": [ "fixed_value" ], "key": "renewal_settings.renew_expired_cert", "value": "anytime" }, { "optional": false, "enabled": true, "sources": [ "fixed_value" ], "key": "renewal_settings.renew_revoked_cert", "value": true }, { "optional": false, "enabled": true, "sources": [ "fixed_value" ], "key": "renewal_settings.renewal_key_pair", "value": "optional" } ], "divisions": [ "cbea7aed-4b1d-467e-b45e-ad92137081de", "ece99208-8a31-4298-9a90-a946c3038569", "370c5ca7-7774-431b-bc31-e03c067a2a31" ] } }, "updateCertificateProfileRequest": { "type": "object", "required": [ "name", "body" ], "properties": { "name": { "type": "string", "description": "Unique certificate profile name.", "example": "Example certificate profile" }, "body": { "type": "array", "description": "List of objects that configures certificate fields for the certificate profile.", "items": { "type": "object", "required": [ "key", "optional", "enabled", "sources", "value" ], "properties": { "key": { "type": "string", "description": "Certificate field key.", "enum": [ "csr", "certificate_value", "unique_certificate_value", "signature_algorithm", "allow_any_key_type", "allowed_key_types", "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.street_address", "subject.postal_code", "subject.locality", "subject.state", "subject.country", "subject.email", "subject.unique_identifier", "validity.duration_unit", "validity.duration_value", "key_usage.critical", "extended_key_usage.critical", "extended_key_usage.additional_values", "renewal_settings.renew_valid_cert", "renewal_settings.renew_expired_cert", "renewal_settings.renew_revoked_cert", "renewal_settings.renewal_key_pair" ] }, "optional": { "type": "boolean", "description": "If true, the field is optional. If false, the field is required." }, "sources": { "type": "array", "description": "List of value sources for the field.", "items": { "type": "string", "description": "Source.", "enum": [ "csr", "fixed_value", "user_supplied" ] } }, "value": { "type": "string", "description": "Default field value." }, "enabled": { "type": "boolean", "description": "If true, the field is enabled. Otherwise, false." } } } }, "divisions": { "type": "array", "description": "List of IDs for each division to assign to the certificate profile.", "items": { "$ref": "#/components/schemas/division_id" } } }, "example": { "name": "New certificate profile", "body": [ { "key": "csr", "optional": false, "enabled": true, "sources": [ "user_supplied" ], "value": "" }, { "key": "certificate_value", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "auto" }, { "key": "unique_certificate_value", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "no" }, { "key": "signature_algorithm", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "match_issuer" }, { "key": "allow_any_key_type", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "yes" }, { "key": "allowed_key_types", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": [ "rsa_2048", "rsa_3072", "rsa_4096", "p_256", "p_384", "p_521", "ed_25519" ] }, { "key": "subject.common_name", "optional": false, "enabled": true, "sources": [ "user_supplied", "csr" ], "value": "" }, { "key": "subject.organization_name", "optional": true, "enabled": true, "sources": [ "user_supplied", "csr" ], "value": "" }, { "key": "subject.organization_unit", "optional": true, "enabled": false, "sources": [], "value": [] }, { "key": "subject.street_address", "optional": true, "enabled": false, "sources": [], "value": [] }, { "key": "subject.postal_code", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "subject.locality", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "subject.state", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "subject.country", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "subject.email", "optional": true, "enabled": false, "sources": [], "value": "" }, { "key": "validity.duration_unit", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": "months" }, { "key": "validity.duration_value", "optional": false, "enabled": true, "sources": [ "fixed_value" ], "value": 9 }, { "key": "key_usage.critical", "optional": true, "enabled": false, "sources": [ "fixed_value" ], "value": "yes" }, { "key": "extended_key_usage.critical", "optional": true, "enabled": false, "sources": [ "fixed_value" ], "value": "yes" }, { "key": "extended_key_usage.additional_values", "optional": true, "enabled": false, "sources": [], "value": [] }, { "optional": false, "enabled": true, "sources": [ "fixed_value" ], "key": "renewal_settings.renew_valid_cert", "value": "anytime" }, { "optional": false, "enabled": true, "sources": [ "fixed_value" ], "key": "renewal_settings.renew_expired_cert", "value": "anytime" }, { "optional": false, "enabled": true, "sources": [ "fixed_value" ], "key": "renewal_settings.renew_revoked_cert", "value": true }, { "optional": false, "enabled": true, "sources": [ "fixed_value" ], "key": "renewal_settings.renewal_key_pair", "value": "optional" } ], "divisions": [ "2d2b5869-e173-4baf-ac65-21f198dc8963", "575cf715-b996-4428-ad3b-a74294f05a74", "2b94fd30-89bf-4cc2-ba6d-d7d7c6358cd5" ] } }, "authenticationCACertificateResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Authentication CA certificate ID (UUID).", "example": "f40fd4b5-f5ed-4cba-ac97-ebabb98e1505", "format": "uuid" }, "name": { "type": "string", "description": "Authentication CA certificate name.", "example": "Authentication CA certificate name" }, "body": { "type": "string", "description": "Authentication CA certificate body.", "example": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n" }, "thumbprint": { "type": "string", "description": "Authentication CA certificate SHA256 thumbprint.", "example": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143" }, "serial_number": { "type": "string", "description": "Authentication CA certificate serial number.", "example": "3031D3B7E49697B5BFF95F972E8C917D5A2BDE4D" }, "internal": { "type": "boolean", "description": "Not used. Always true.", "example": true }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time the authentication CA certificate was created. Format: UTC timezone and ISO 8601 date.\n", "example": "2020-10-02T21:16:02Z" }, "number_of_enrollment_profiles": { "type": "number", "description": "Number of enrollment profiles using the authentication CA certificate.\n", "example": 1 }, "valid_from": { "type": "string", "format": "date", "description": "Start date of the authentication CA certificate validity period. Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2021-06-09T13:54:07Z" }, "valid_to": { "type": "string", "format": "date", "description": "End date of the authentication CA certificate validity period. Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2051-06-09T13:06:23Z" }, "force_restrictions": { "type": "boolean", "description": "Not used. Always false.\n", "example": false }, "organization": { "type": "string", "description": "Subject Distinguished Name (DN) organization on the authentication CA certificate.\n", "example": "Example organization" }, "key_type": { "type": "string", "description": "Authentication CA certificate's key type.\n", "example": "EC prime256v1" }, "signature_algorithm": { "type": "string", "description": "Object Identifier (OID) for the authentication CA certificate's signature algorithm.\n", "example": "1.2.840.10045.4.3.2" }, "status": { "type": "string", "description": "Authentication CA certificate status.", "enum": [ "ACTIVE", "DISABLED", "DELETED" ], "example": "ACTIVE" } } }, "createAuthenticationCATemplateRequest": { "required": [ "name", "enrollment_profile_id", "ica_id", "ica_body", "can_be_used_for_any_certificate" ], "allOf": [ { "type": "object", "properties": { "enrollment_profile_id": { "$ref": "#/components/schemas/enrollment_profile_id" }, "ica_id": { "type": "string", "description": "ID of an existing authentication CA certificate to use in the template. Required if no `ica_body` is specified. To retrieve a list of existing authentication CA certificates, use the **List authentication CA certificates** endpoint (GET `/account/{account_id}/authentication-ca`).\n", "example": "64a17c67-44b9-4ac1-b5a0-4f3fcb2e851b" }, "ica_body": { "type": "string", "description": "PEM-encoded certificate body of a new authentication CA certificate to use in the template. Required if no `ica_id` is specified.", "example": null } } }, { "$ref": "#/components/schemas/authenticationCATemplateRequest" } ], "example": { "can_be_used_for_any_certificate": false, "certificate_authentication_type": "certificate_body_and_attributes", "name": "Example authentication CA template", "ica_id": "2c4098a5-9290-4b4f-9745-7a11095cdb8b", "ica_body": "", "certificate_attributes": [ "subject.common_name", "subject.organization_name" ], "usage_limit": 20, "start_date": "2022-07-21", "end_date": "2022-07-31", "registered_values": [ { "value": "US", "certificate_field": "subject.country" } ], "enrollment_profile_id": "IOT_5a769cca-21de-43e4-8950-5afac965d3df" } }, "authenticationCATemplateRequest": { "type": "object", "description": "Object with authentication CA template details.", "properties": { "name": { "type": "string", "description": "Authentication CA template friendly name.", "example": "Example authentication CA template" }, "can_be_used_for_any_certificate": { "type": "boolean", "description": "If true, any certificate issued from the template's authentication CA certificate is a valid authentication credential for the enrollment profile. If false, use the `certificate_authentication_type` field to choose how you want to limit which authentication certificates can be used as valid credentials.\n", "example": true }, "certificate_authentication_type": { "type": "string", "description": "If `can_be_used_for_any_certificate` is false, choose how you want to limit which certificates issued from the template's authentication CA certificate can be used as authentication credentials for the enrollment profile.\n\nPossible values:\n- `certificate_body`: Upload allowed authentication certificates. To upload authentication certificates, use the **Upload authentication certificate** endpoint (POST `/authentication-certificate`) after creating the authentication CA template.\n- `certificate_attributes`: Use the `certificate_attributes` field to define required attributes for valid authentication certificates.\n- `certificate_body_and_attributes`: Use the `certificate_attributes` field to define required attributes for valid authentication certificates and/or upload the allowed authentication certificates.\n", "enum": [ "certificate_body", "certificate_attributes", "certificate_body_and_attributes" ] }, "certificate_attributes": { "type": "array", "description": "List of one or more required certificate attributes for valid authentication certificates. This field is conditionally required based on the value of `certificate_authentication_type`:\n * `certificate_attributes`: required\n * `certificate_body_and_attributes`: optional\n * `certificate_body`: ignored\n", "items": { "type": "string", "description": "Certificate attribute.", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "subject.unique_identifier" ] } }, "usage_limit": { "type": "number", "description": "Number of times the authentication CA template can be used for enrollment. If not provided, there is no usage limit.", "example": null }, "start_date": { "type": "string", "description": "Start date for the period of time during which the enrollment profile can use the authentication CA template. If not provided, there is no start date limitation. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-01-01" }, "end_date": { "type": "string", "description": "End date for the period of time during which the enrollment profile can use the authentication CA template. If not provided, there is no end date limitation. Format: `YYYY-MM-DD`\n", "format": "date-time", "example": "2021-01-01" }, "registered_values": { "type": "array", "description": "List of objects with details about the certificate fields to validate when using these credentials with the assigned enrollment profile. If you don't need to validate certificate fields for these credentials, omit the `registered_values` object from your request.", "items": { "type": "object", "properties": { "certificate_field": { "type": "string", "description": "Name of a certificate field to validate when using the credentials.", "example": "subject.common_name", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "subject.unique_identifier", "challenge_password" ] }, "value": { "description": "A value or list of values to compare with the value of the chosen `certificate_field`. Use a string to validate certificate fields that contain a string. Use an array to validate certificate fields that contain an array.", "example": "example", "oneOf": [ { "type": "string", "example": "example" }, { "type": "array", "items": {}, "example": [ "example1", "example2" ] } ] } } } }, "force_passcode_for_auth_cert": { "type": "boolean", "default": false, "description": "If `true`, authentication certificates using the template require a passcode. Otherwise, defining a passcode for authentication certificates is optional.\n\nTo enable this parameter:\n* The `API` enrollment method must be enabled for the template's enrollment profile.\n* The value of the `can_be_used_for_any_certificate` parameter must be `false`. In other words, a template cannot require passcodes for authentication certificates if the template allows any certificates issued from the authentication CA to be used as credentials.\n" } } }, "authenticationCATemplateResponse": { "type": "object", "description": "Object with authentication CA template details.", "properties": { "id": { "type": "string", "description": "Authentication CA template ID (UUID).", "format": "uuid", "example": "fd1e733c-1ecd-4c27-98d6-fb86b92fa377" }, "name": { "type": "string", "description": "Authentication CA template friendly name.", "example": "Example authentication CA template" }, "certificate_attributes": { "type": "array", "description": "List of one or more required certificate attributes for valid authentication certificates.\n", "items": { "type": "string", "description": "Certificate attribute.", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "subject.unique_identifier" ] } }, "registered_values": { "type": "array", "description": "List of objects with details about the certificate fields to validate when using these credentials with the assigned enrollment profile.", "items": { "type": "object", "properties": { "certificate_field": { "type": "string", "description": "Name of a certificate field to validate when using the credentials.", "example": "subject.common_name", "enum": [ "subject.common_name", "subject.organization_name", "subject.organization_unit", "subject.country", "subject.state", "subject.locality", "subject.street_address", "subject.postal_code", "subject.email", "challenge_password" ] }, "matcher": { "type": "string", "description": "Operator used when comparing the value of the certificate field to the registered values.", "enum": [ "equals" ], "example": "equals" }, "value": { "description": "A value or list of values to compare with the value of the chosen `certificate_field`. Use a string to validate certificate fields that contain a string. Use an array to validate certificate fields that contain an array.", "oneOf": [ { "type": "string" }, { "type": "array", "items": {} } ] }, "multiple": { "type": "boolean", "description": "Returns `true` when the data type of the certificate field is an array. Otherwise, `false`.", "example": false } } } }, "enrollment_profile_id": { "$ref": "#/components/schemas/enrollment_profile_id" }, "enrollment_profile_name": { "type": "string", "description": "Enrollment profile name.", "example": "Example enrollment profile" }, "ica_common_name": { "type": "string", "description": "Authentication CA certificate common name.", "example": "Example CA certificate" }, "ica_body": { "type": "string", "description": "Authentication CA certificate body.", "example": "-----BEGIN CERTIFICATE-----\\n...-----END CERTIFICATE-----\\n" }, "organization": { "type": "string", "description": "Subject Distinguished Name (DN) organization on the authentication CA certificate.\n", "example": "Example organization" }, "parent_ca": { "type": "string", "description": "Common name of the CA certificate that issued the template's authentication CA certificate.", "example": "Example issuing CA certificate" }, "signature_algorithm": { "type": "string", "description": "Object Identifier (OID) for the authentication CA certificate's signature algorithm.\n", "example": "1.2.840.10045.4.3.2" }, "key_type": { "type": "string", "description": "Authentication CA certificate's key type.\n", "example": "EC prime256v1" }, "can_be_used_for_any_certificate": { "type": "boolean", "description": "If true, any certificate issued from the template's authentication CA certificate is a valid authentication credential for the enrollment profile. If false, the `certificate_authentication_type` field describes how to limit which authentication certificates can be used as valid credentials.\n", "example": true }, "certificate_authentication_type": { "type": "string", "description": "If `can_be_used_for_any_certificate` is false, this field describes how to limit which certificates issued from the template's authentication CA certificate can be used as authentication credentials for the enrollment profile.\n\nPossible values:\n- `certificate_body`: Upload allowed authentication certificates. To upload authentication certificates, use the **Upload authentication certificate** endpoint (POST `/authentication-certificate`) after creating the authentication CA template.\n- `certificate_attributes`: Use the `certificate_attributes` field to define required attributes for valid authentication certificates.\n- `certificate_body_and_attributes`: Use the `certificate_attributes` field to define required attributes for valid authentication certificates and/or upload the allowed authentication certificates.\n", "enum": [ "certificate_body", "certificate_attributes", "certificate_body_and_attributes", "not_applicable" ] }, "usage_limit": { "type": "number", "description": "Number of times the authentication CA template can be used for enrollment. If not provided, there is no usage limit.", "example": null }, "start_date": { "type": "string", "description": "Start date for the period of time during which the enrollment profile can use the authentication CA template.\n", "format": "date-time", "example": "2021-01-01" }, "end_date": { "type": "string", "description": "End date for the period of time during which the enrollment profile can use the authentication CA template.\n", "format": "date-time", "example": "2021-01-01" }, "expiry_date": { "type": "string" }, "status": { "type": "string", "description": "Authentication CA template status.", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time the authentication CA template was created. Format: UTC timezone and ISO 8601 date.\n", "example": "2020-10-02T21:16:02Z" }, "force_passcode_for_auth_cert": { "type": "boolean", "default": false, "description": "If `true`, authentication certificates using the template require a passcode. Otherwise, defining a passcode for authentication certificates is optional.\n" } }, "example": { "id": "55f6e0e5-8cbf-4f7b-a623-f5b9689a0dc2", "name": "Example authentication CA template", "certificate_attributes": [ "subject.common_name", "subject.organization_name" ], "registered_values": [ { "certificate_field": "subject.country", "matcher": "equals", "value": "US", "multiple": false } ], "enrollment_profile_id": "IOT_58b96f06-bf12-49a4-939e-7247f147ec3e", "enrollment_profile_name": "Example enrollment profile", "ica_common_name": "IoT Example ICA", "ica_body": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n", "organization": "IoT Example Organization", "parent_ca": "IoT Example Root", "signature_algorithm": "1.2.840.10045.4.3.2", "key_type": "EC prime256v1", "can_be_used_for_any_certificate": false, "certificate_authentication_type": "certificate_body_and_attributes", "usage_limit": 20, "start_date": "2022-07-21", "end_date": "2022-07-31", "expiry_date": "2049-01-01", "status": "ACTIVE", "created_at": "2022-07-21T10:09:13Z", "force_passcode_for_auth_cert": false } }, "assignableAuthenticationCACertificateResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Authentication CA certificate ID (UUID).", "example": "f40fd4b5-f5ed-4cba-ac97-ebabb98e1505", "format": "uuid" }, "common_name": { "type": "string", "description": "Authentication CA certificate common name.", "example": "Authentication CA certificate common name" }, "organization": { "type": "string", "description": "Organization on the authentication CA certificate.\n", "example": "Example organization" }, "key_type": { "type": "string", "description": "Authentication CA certificate's key type.\n", "example": "EC prime256v1" }, "signature_algorithm": { "type": "string", "description": "Authentication CA certificate's signature algorithm.\n", "example": "sha256WithRSA", "enum": [ "sha1WithRSA", "sha256WithRSA", "sha384WithRSA", "sha512WithRSA", "sha256WithECDSA", "sha384WithECDSA", "sha512WithECDSA", "sha3_256WithRSA", "sha3_384WithRSA", "sha3_512WithRSA" ] }, "issuer_common_name": { "type": "string", "description": "Common name of the issuing CA certificate.\n", "example": "Issuing CA certificate common name" }, "body": { "type": "string", "description": "Authentication CA certificate body.", "example": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n" }, "valid_from": { "type": "string", "format": "date", "description": "Start date of the authentication CA certificate validity period. Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2021-06-09T13:54:07Z" }, "valid_to": { "type": "string", "format": "date", "description": "End date of the authentication CA certificate validity period. Format: `YYYY-MM-DDThh:mm:ss.sTZD`\n", "example": "2051-06-09T13:06:23Z" }, "serial_number": { "type": "string", "description": "Authentication CA certificate serial number.", "example": "3031D3B7E49697B5BFF95F972E8C917D5A2BDE4D" }, "thumbprint": { "type": "string", "description": "Authentication CA certificate SHA256 thumbprint.", "example": "f99a9e95b9b7c40b985b36ea7a444801ed177ad5bd9aa4464f53694df2b98143" } } }, "divisionResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique division name.", "example": "Example division name" }, "description": { "type": "string", "description": "Custom division description.", "example": "Example division description" }, "id": { "$ref": "#/components/schemas/division_id" }, "account": { "type": "object", "description": "Object with name and ID of account the division belongs to.", "properties": { "id": { "$ref": "#/components/schemas/account_id" }, "name": { "type": "string", "description": "Account name.", "example": "Example account." } } }, "status": { "type": "string", "description": "Division status.", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time the division was created. Format: UTC timezone and ISO 8601 format.\n", "example": "2020-11-05T08:36:50Z" } } }, "gatewayResponse": { "type": "object", "properties": { "id": { "description": "Gateway ID.", "format": "uuid", "example": "ebabb32a-7937-40ea-bbfd-8cbdae417512", "type": "string" }, "account_id": { "type": "string", "format": "uuid", "example": "1331f16c-7e4e-4e5e-9187-27f951d46924", "description": "Account ID." }, "name": { "description": "Gateway name.", "type": "string", "example": "Example gateway" }, "description": { "type": "string", "description": "Custom gateway description.", "example": "Example gateway object" }, "ip_addresses": { "type": "array", "description": "List of IP addresses for allowed gateway hosts. Single IPs, IP ranges, and wildcards allowed. If no IP address restrictions exist, returns an empty array.", "items": { "type": "string", "description": "IP address.", "example": "192.0.2.0" } }, "mac_address": { "type": "string", "example": "gg-hh-ii-kk-ll-mm", "description": "MAC address for the gateway host server." }, "status": { "type": "string", "example": "ACTIVE", "description": "Gateway status.", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "created_at": { "type": "string", "description": "Date and time the gateway was created. UTC timezone and ISO 8601 format.", "example": "2023-01-11T08:49:45.557679Z" }, "http_enabled": { "type": "boolean", "description": "If true, HTTP protocol is enabled for the gateway host server. Otherwise, false." }, "http_port": { "type": "string", "description": "Port at which the gateway host server is listening for HTTP requests. Omitted from response if `http_enabled` is false.", "example": "8080" }, "ssl_enabled": { "type": "boolean", "description": "If true, HTTPS protocol is enabled for the gateway host server. Otherwise, false." }, "ssl_port": { "type": "string", "description": "Port at which the gateway host server is listening for HTTPS requests. Omitted from response if `ssl_enabled` is false.", "example": "8443" }, "ssl_certificate_pkcs12_file_path": { "type": "string", "description": "Path to PKCS12 keystore file with SSL certificate and corresponding private key. Omitted from response if `ssl_enabled` is false.", "example": "config/gateway.p12" }, "ssl_certificate_pkcs12_key_store_password": { "type": "string", "description": "Partially masked SSL keystore password. Omitted from response if `ssl_enabled` is false.", "example": "********rd" }, "server_user_email": { "type": "string", "description": "Server User email address.", "example": "jane.doe@example.com" }, "use_authentication_api_token": { "type": "boolean", "description": "If true, the gateway authenticates itself to DigiCert® IoT Trust Manager using an API token. Either `use_authentication_api_token` or `use_authentication_certificate` must be true." }, "authentication_api_token": { "type": "string", "description": "Partially masked API token. Omitted from response if `use_authentication_api_token` is false.", "example": "********1234" }, "use_authentication_certificate": { "type": "boolean", "description": "If true, the gateway authenticates itself to DigiCert® IoT Trust Manager using an authentication certificate. Either `use_authentication_api_token` or `use_authentication_certificate` must be true." }, "authentication_certificate_pkcs12_password": { "type": "string", "description": "Partially masked password for the PKCS12 file with the authentication certificate and corresponding private key. Omitted from response if `use_authentication_certificate` is false.", "example": "********123" }, "authentication_certificate_pkcs12_name": { "type": "string", "description": "Authentication certificate name. Omitted if nonexistent.", "example": "Example authentication certificate" }, "config_status": { "type": "string", "description": "Gateway configuration status.\n\n- `completed`: Gateway configuration is complete and the configuration can be downloaded.\n- `in_progress`: Gateway status incomplete and the configuration details are not available to download.\n", "enum": [ "complete", "in_progress" ] }, "config_updated_at": { "type": "string", "format": "date-time", "description": "Date and time of the last update to the gateway that changed the configuration file. UTC timezone and ISO 8601 format." }, "config_downloaded_at": { "type": "string", "format": "date-time", "description": "Date and time of the configuration file's most recent download. UTC timezone and ISO 8601 format." }, "recent_config_was_downloaded": { "type": "boolean", "description": "If true, the configuration file was downloaded after its latest update. Otherwise, false." } }, "example": { "id": "ebabb32a-7937-40ea-bbfd-8cbdae417512", "account_id": "1331f16c-7e4e-4e5e-9187-27f951d46924", "name": "Example gateway", "description": "Example gateway object", "ip_addresses": [], "mac_address": "gg-hh-ii-kk-ll-mm", "status": "ACTIVE", "created_at": "2023-01-11T08:49:45.557679Z", "http_enabled": true, "http_port": "8080", "ssl_enabled": true, "ssl_port": "8443", "ssl_certificate_pkcs12_file_path": "config/gateway.p12", "ssl_certificate_pkcs12_key_store_password": "********rd", "use_authentication_api_token": true, "authentication_api_token": "********1234", "use_authentication_certificate": false, "config_status": "complete", "config_updated_at": "2023-01-27T18:13:02Z", "config_downloaded_at": "2023-01-27T18:13:04Z", "recent_config_was_downloaded": true } }, "gatewayRequest": { "type": "object", "required": [ "account_id", "name" ], "properties": { "account_id": { "type": "string", "format": "uuid", "example": "1331f16c-7e4e-4e5e-9187-27f951d46924", "description": "Gateway account ID." }, "name": { "description": "Gateway name. Character limit: 64\n", "type": "string", "maxLength": 64, "example": "Example gateway" }, "description": { "type": "string", "description": "Custom gateway description. Character limit: 255\n", "example": "Example gateway object", "maxLength": 255 }, "ip_addresses": { "type": "array", "description": "List of IP addresses for allowed gateway hosts. Single IPs, IP ranges, and wildcards allowed. If empty or not provided, any IP address is allowed.\n\nFormat examples:\n\n - Single IP address: 192.168.1.2\n - Range: 192.168.2.120-150\n - Wildcard: 192.168.2**.4\n", "items": { "type": "string", "description": "IP address.", "example": "192.0.2.0" } } }, "example": { "account_id": "1331f16c-7e4e-4e5e-9187-27f951d46924", "name": "Example gateway", "description": "Example gateway object", "ip_addresses": [] } }, "gatewayCreateRequest": { "type": "object", "required": [ "account_id", "name" ], "properties": { "account_id": { "type": "string", "format": "uuid", "example": "1331f16c-7e4e-4e5e-9187-27f951d46924", "description": "Gateway account ID." }, "name": { "description": "Gateway name. Character limit: 64\n", "type": "string", "maxLength": 64, "example": "Example gateway" }, "description": { "type": "string", "description": "Custom gateway description. Character limit: 255\n", "example": "Example gateway object", "maxLength": 255 }, "mac_address": { "type": "string", "example": "gg-hh-ii-kk-ll-mm", "description": "MAC address for the gateway host server." }, "ip_addresses": { "type": "array", "description": "List of IP addresses for allowed gateway hosts. Single IPs, IP ranges, and wildcards allowed. If empty or not provided, any IP address is allowed.\n\nFormat examples:\n\n - Single IP address: 192.168.1.2\n - Range: 192.168.2.120-150\n - Wildcard: 192.168.2**.4\n", "items": { "type": "string", "description": "IP address.", "example": "192.0.2.0" } } }, "example": { "account_id": "1331f16c-7e4e-4e5e-9187-27f951d46924", "name": "Example gateway", "description": "Example gateway object", "ip_addresses": [] } }, "OCSPGroupResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "OCSP group ID (UUID).", "format": "uuid", "example": "f8b4ae8b-7094-491c-a2c0-f4d2b45c7857" }, "name": { "type": "string", "description": "OCSP group name.", "example": "Example OCSP group" }, "status": { "type": "string", "description": "OCSP group status.", "example": "ACTIVE" }, "division_id": { "type": "string", "description": "Division ID for certificates in the OCSP group (UUID).", "example": "80423721-51e1-4489-a983-ff695c662620", "format": "uuid" }, "division_name": { "type": "string", "description": "Division name for certificates in the OCSP group (UUID).", "example": "249ded7e-7989-4b5c-9b9e-bd8415e7170c", "format": "uuid" }, "ica_id": { "type": "string", "description": "ID of the issuing CA for certificates in the OCSP group.", "example": "266E9B7B2C093845D7856CDB4B7E0914" }, "ica_name": { "type": "string", "description": "Name of the issuing CA for certificates in the OCSP group.", "example": "Example ICA" }, "ica_body": { "type": "string", "description": "PEM-encoded certificate body of the issuing CA for certificates in the OCSP group.", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n" }, "ica_serial_number": { "type": "string", "description": "Serial number of the issuing CA for certificates in the OCSP group.", "example": "1234D1B7345647B5B6F95F572E8C917D5A123456" }, "created_at": { "type": "string", "description": "Date and time the OCSP group was created. Format: UTC timezone and ISO 8601 format.\n", "format": "date-time", "example": "2023-02-17T23:25:08Z" }, "contains_expired_certificates": { "type": "boolean", "description": "If true, the OCSP group has at least one expired certificate. Otherwise, false.", "example": false } }, "example": { "id": "974bd09b-99e7-41f4-a26b-0d1ae5473fb7", "name": "OCSP group", "status": "ACTIVE", "division_id": "5c4d4e37-b0f9-459a-846a-50e9fdb54da1", "division_name": "IoT Division", "ica_id": "266E9B7B2C093845D7856CDB4B7E0914", "ica_name": "RSA ICA OCSP", "ica_body": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n", "ica_serial_number": "1234D1B7345647B5B6F95F572E8C917D5A123456", "created_at": "2023-02-13T12:18:47Z", "contains_expired_certificates": false } }, "OCSPGroupRequest": { "type": "object", "required": [ "name", "certificates", "division_id" ], "properties": { "name": { "type": "string", "description": "OCSP group name. Must be unique within the account. Character limit: 64\n", "maxLength": 64, "example": "Example OCSP group" }, "certificates": { "type": "array", "description": "List of IDs for certificates in the OCSP group.\n\nRequirements:\n\n- All certificates must be issued through the same division (`division_id`) and must have the same issuing CA.\n\n- The issuing CA for certificates in the group must be configured to include OCSP.\n\n- Certificates already in an OCSP group cannot be added to another OCSP group.\n\n- An OCSP group must have at least one certificate. Empty lists are not allowed.\n", "minItems": 1, "example": [ "81133e8f-6b0d-4bf1-ac9e-402e72e006b0", "6ef9246f-e071-4a8e-a871-0ea4314cde64", "5be444dd-ea46-4cac-9e15-823d16012c69" ], "items": { "type": "string", "format": "uuid", "description": "Certificate ID (UUID).", "example": "146c88ae-8db9-4186-9a4a-dcfd267b67dd" } }, "division_id": { "type": "string", "description": "ID of the division certificates in the OCSP group were issued through.", "format": "uuid", "example": "3f8f4482-1e31-4840-831e-9416b1dec1f5" } } }, "TrustBundleResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "trust bundle ID (UUID).", "format": "uuid", "example": "f8b4ae8b-7094-491c-a2c0-f4d2b45c7857" }, "name": { "type": "string", "description": "trust bundle name.", "example": "Example OCSP group" }, "status": { "type": "string", "description": "trust bundle status.", "example": "ACTIVE" }, "account_id": { "type": "string", "description": "Account ID of trust bundle (UUID).", "example": "80423721-51e1-4489-a983-ff695c662620", "format": "uuid" }, "default_format": { "type": "string", "description": "Default trust bundle download format.", "example": "single_pem", "enum": [ "individual_crt", "individual_pem", "individual_cer", "individual_der", "single_p7b", "single_pem" ] }, "default_extension": { "type": "string", "description": "Default file extension for default download format.", "example": "pem" }, "limited_by_divisions": { "type": "boolean", "description": "When true trust bundle access is limited by divisions.", "example": true }, "description": { "type": "string", "description": "trust bundle description.", "example": "Trust Bundle example description." }, "created_at": { "type": "string", "description": "Date and time the trust bundle was created. Format: UTC timezone and ISO 8601 format.\n", "format": "date-time", "example": "2023-02-17T23:25:08Z" }, "updated_at": { "type": "string", "description": "Date and time the trust bundle was last time updated. Format: UTC timezone and ISO 8601 format.\n", "format": "date-time", "example": "2023-02-17T23:25:08Z" }, "certificates": { "type": "array", "description": "Certificates included into trust bundle", "items": { "$ref": "#/components/schemas/TrustBundleCertificateResponse" } } }, "example": { "id": "974bd09b-99e7-41f4-a26b-0d1ae5473fb7", "name": "Trust bundle", "status": "ACTIVE", "account_id": "5c4d4e37-b0f9-459a-846a-50e9fdb54da1", "default_format": "single_p7b", "default_extension": "pem", "limited_by_divisions": true, "description": "Example description", "created_at": "2023-02-13T12:18:47Z", "updated_at": "2023-02-13T12:18:47Z", "certificates": [ { "id": "2a0269ce-b2a2-41f4-8690-4f3666f3a794", "trust_bundle_id": "d63b6a26-41ca-4b9c-9cb3-3c7ca61f59d8", "certificate_body": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", "common_name": "Certificate 001", "serial_number": "1f632ae04d9237b628667d081e955d3e707c74ca", "certificate_valid_from": "2023-11-07T14:32:34Z", "certificate_valid_to": "2024-11-07T14:32:34Z", "status": "ACTIVE", "created_at": "2023-11-23T09:57:15Z" } ] } }, "TrustBundleCertificateResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "trust bundle ID (UUID).", "format": "uuid", "example": "f8b4ae8b-7094-491c-a2c0-f4d2b45c7857" }, "trust_bundle_id": { "type": "string", "description": "trust bundle ID this certificate include into.", "format": "uuid", "example": "d63b6a26-41ca-4b9c-9cb3-3c7ca61f59d8" }, "status": { "type": "string", "description": "certificate status.", "example": "ACTIVE" }, "certificate_body": { "type": "string", "description": "Certificate body in PEM format.", "example": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" }, "common_name": { "type": "string", "description": "certificate common name.", "example": "Certificate 001" }, "serial_number": { "type": "string", "description": "certificate serial number.", "example": "1f632ae04d9237b628667d081e955d3e707c74ca" }, "certificate_valid_from": { "type": "string", "description": "Certificate valididity start date. Format: UTC timezone and ISO 8601 format.\n", "format": "date-time", "example": "2023-02-17T23:25:08Z" }, "certificate_valid_to": { "type": "string", "description": "Certificate valididity end date. Format: UTC timezone and ISO 8601 format.\n", "format": "date-time", "example": "2023-02-17T23:25:08Z" }, "created_at": { "type": "string", "description": "Date and time the certificate was added to trust bundle. Format: UTC timezone and ISO 8601 format.\n", "format": "date-time", "example": "2023-02-17T23:25:08Z" } }, "example": { "id": "974bd09b-99e7-41f4-a26b-0d1ae5473fb7", "trust_bundle_id": "5c4d4e37-b0f9-459a-846a-50e9fdb54da1", "certificate_body": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", "status": "ACTIVE", "common_name": "Certificate 001", "serial_number": "1f632ae04d9237b628667d081e955d3e707c74ca", "certificate_valid_from": "2023-02-13T12:18:47Z", "certificate_valid_to": "2023-02-13T12:18:47Z", "created_at": "2023-02-13T12:18:47Z" } }, "TrustBundleCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "trust bundle name.", "example": "Example OCSP group" }, "account_id": { "type": "string", "description": "Account ID of trust bundle (UUID).", "example": "80423721-51e1-4489-a983-ff695c662620", "format": "uuid" }, "default_format": { "type": "string", "description": "Default trust bundle download format.", "example": "single_pem", "enum": [ "individual_crt", "individual_pem", "individual_cer", "individual_der", "single_p7b", "single_pem" ] }, "default_extension": { "type": "string", "description": "Default file extension for default download format.", "example": "pem" }, "limited_by_divisions": { "type": "boolean", "description": "set to true if you want to limit trust bundle access with specified divisions, otherwise set to false.", "example": true }, "divisions": { "type": "array", "description": "Division IDs to assign to trust bundle (required when updating limited_by_divisions = true)", "items": { "type": "string", "description": "ID of division to assign", "example": "a742a36e-1257-41a9-a107-a01c589e3a98" }, "example": { "divisions": [ "a742a36e-1257-41a9-a107-a01c589e3a98" ] } }, "description": { "type": "string", "description": "trust bundle description.", "example": "Trust Bundle example description." }, "certificates": { "type": "array", "description": "Certificate bodies in PEM format to be included into trust bundle", "items": { "type": "string", "description": "Certificate body in PEM format", "example": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" } } }, "example": { "name": "Trust bundle", "account_id": "5c4d4e37-b0f9-459a-846a-50e9fdb54da1", "default_format": "single_p7b", "description": "Example description", "certificates": [ "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" ], "limited_by_divisions": true, "divisions": [ "a742a36e-1257-41a9-a107-a01c589e3a98" ] } }, "TrustBundleUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "trust bundle name.", "example": "Example OCSP group" }, "default_format": { "type": "string", "description": "Default trust bundle download format.", "example": "single_pem", "enum": [ "individual_crt", "individual_pem", "individual_cer", "individual_der", "single_p7b", "single_pem" ] }, "default_extension": { "type": "string", "description": "Default file extension for default download format.", "example": "pem" }, "description": { "type": "string", "description": "trust bundle description.", "example": "Trust Bundle example description." } }, "example": { "name": "Trust bundle", "default_format": "single_p7b", "description": "Example description" } }, "TrustBundleAddCertificatesRequest": { "type": "object", "properties": { "certificates": { "type": "array", "description": "Certificate bodies in PEM format to be included into trust bundle", "items": { "type": "string", "description": "Certificate body in PEM format", "example": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" } } }, "example": { "certificates": [ "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" ] } }, "TrustBundleRemoveCertificatesRequest": { "type": "object", "properties": { "certificates": { "type": "array", "description": "Certificate IDs to be removed trust bundle", "items": { "type": "string", "description": "Certificate body in PEM format", "example": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" } } }, "example": { "certificates": [ "2a0269ce-b2a2-41f4-8690-4f3666f3a794" ] } }, "TrustBundleUpdateLimitedByDivisionRequest": { "type": "object", "properties": { "limited_by_divisions": { "type": "boolean", "description": "set to true if you want to limit trust bundle access with specified divisions, otherwise set to false.", "example": true }, "divisions": { "type": "array", "description": "Division IDs to assign to trust bundle (required when updating limited_by_divisions = true)", "items": { "type": "string", "description": "ID of division to assign", "example": "a742a36e-1257-41a9-a107-a01c589e3a98" }, "example": { "divisions": [ "a742a36e-1257-41a9-a107-a01c589e3a98" ] } } }, "example": { "limited_by_divisions": true } }, "TrustBundleAssignDivisionsRequest": { "type": "object", "properties": { "divisions": { "type": "array", "description": "Division IDs to assign to trust bundle", "items": { "type": "string", "description": "ID of division to assign", "example": "a742a36e-1257-41a9-a107-a01c589e3a98" } } }, "example": { "divisions": [ "a742a36e-1257-41a9-a107-a01c589e3a98" ] } }, "TrustBundleRemoveDivisionsRequest": { "type": "object", "properties": { "divisions": { "type": "array", "description": "Division IDs to remove from trust bundle", "items": { "type": "string", "description": "ID of division to remove", "example": "a742a36e-1257-41a9-a107-a01c589e3a98" } } }, "example": { "divisions": [ "a742a36e-1257-41a9-a107-a01c589e3a98" ] } } }, "examples": { "clientSideDefault": { "summary": "Client-side keypair generation with chain\n", "description": "Example response for a request with default request parameter values. In the response, the `pem` parameter contains the full certificate chain (end-entity certificate, ICA certificate, and root certificate) as a single concatenated string.\n", "value": { "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..." } }, "clientSideWithoutChain": { "summary": "Client-side keypair generation without chain\n", "description": "Example response for a request with `include_certificate_chain` set to false. In the response, the `pem` parameter only contains the end-entity certificate.\n", "value": { "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", "ica": "MII..." } }, "clientSideSplitCertificateResponse": { "summary": "Client-side keypair generation with chain (split response)\n", "description": "Example response for a request with `split_certificate_response` set to true. In the response, the `pem` parameter contains the end-entity certificate. The `chain` array returns each certificate in the certificate chain (ICA and root certificate).\n", "value": { "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", "ica": "MII...", "chain": [ { "type": "intermediate", "body": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n" }, { "type": "root", "body": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n" } ] } }, "serverSidePEM": { "summary": "Server-side keypair generation (pem)\n", "description": "Example response for a request using server-side keypair generation with a `private_key_format` value of `pem`. In the response, the `private_key` parameter contains the private key in PEM format.\n\nBy default, the `pem` parameter contains the full certificate chain (end-entity certificate, ICA certificate, and root certificate) as a single concatenated string. To omit the certificate chain or return the certificate chain separately, use the `include_certificate_chain` and `split_certificate_response` request parameters.\n", "value": { "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...", "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" } }, "serverSideDER": { "summary": "Server-side keypair generation (der)\n", "description": "Example response for a request using server-side keypair generation with a `private_key_format` value of `der`. In the response, the `private_key` parameter contains the private key in DER format.\n\nBy default, the `pem` parameter contains the full certificate chain (end-entity certificate, ICA certificate, and root certificate) as a single concatenated string. To omit the certificate chain or return the certificate chain separately, use the `include_certificate_chain` and `split_certificate_response` request parameters.\n", "value": { "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...", "private_key": "" } }, "serverSidePKCS12": { "summary": "Server-side keypair generation (PKCS12)\n", "description": "Example response for a request using server-side keypair generation with a `private_key_format` value of `pkcs_12`. In the response, the `private_key` parameter contains the base64-encoded PKCS12 file with the private key. To access the decoded PKCS12 file, use the password you provided in the request (`pkcs12_password`).\n\nBy default, the `pem` parameter contains the full certificate chain (end-entity certificate, ICA certificate, and root certificate) as a single concatenated string. To omit the certificate chain or return the certificate chain separately, use the `include_certificate_chain` and `split_certificate_response` request parameters.\n", "value": { "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...", "private_key": "" } }, "serverSideCertEncrypted": { "summary": "Server-side keypair generation (cert_encrypted)\n", "description": "Example response for a request using server-side keypair generation with a `private_key_format` value of `cert_encrypted`. In the response, the `private_key` parameter contains the encrypted and base64-encoded compressed ZIP file with the private key, end-entity certificate, and certificate chain. The ZIP file includes the certificate chain only when `include_certificate_chain` is set to true.\n\nBy default, the `pem` parameter contains the full certificate chain (end-entity certificate, ICA certificate, and root certificate) as a single concatenated string. To omit the certificate chain or return the certificate chain separately, use the `include_certificate_chain` and `split_certificate_response` request parameters.\n", "value": { "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...", "private_key": "" } }, "downloadBatchCertificatePKCS12": { "summary": "PKCS12 download\n", "description": "Example response for private key and certificate data in PKCS12 format.", "value": { "certificate_id": "b5db525b-fff8-44de-abab-fd4e8b68f2c5", "format": "pkcs12", "pkcs12": "", "pkcs12_password": "" } }, "downloadBatchCertificatePEM": { "summary": "PEM download\n", "description": "Example response for private key and certificate data in PEM format.", "value": { "certificate_id": "b5db525b-fff8-44de-abab-fd4e8b68f2c5", "format": "pem", "certificate": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n", "private_key": "-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY-----\n", "chain": [ { "cert_type": "intermediate", "blob": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n" }, { "cert_type": "root", "blob": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n" } ] } }, "downloadBatchCertificatePKCS12List": { "summary": "PKCS12 download\n", "description": "Example response for private key and certificate data in PKCS12 format.", "value": [ { "certificate_id": "b5db525b-fff8-44de-abab-fd4e8b68f2c5", "format": "pkcs12", "pkcs12": "", "pkcs12_password": "" }, { "certificate_id": "392bdf9a-cde4-4b80-adb7-421ca343f4f3", "format": "pkcs12", "pkcs12": "", "pkcs12_password": "" } ] }, "downloadBatchCertificatePEMList": { "summary": "PEM download\n", "description": "Example response for private key and certificate data in PEM format.", "value": [ { "certificate_id": "b5db525b-fff8-44de-abab-fd4e8b68f2c5", "format": "pem", "certificate": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n", "private_key": "-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY-----\n", "chain": [ { "cert_type": "intermediate", "blob": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n" }, { "cert_type": "root", "blob": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n" } ] }, { "certificate_id": "392bdf9a-cde4-4b80-adb7-421ca343f4f3", "format": "pem", "certificate": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n", "private_key": "-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY-----\n", "chain": [ { "cert_type": "intermediate", "blob": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n" }, { "cert_type": "root", "blob": "-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n" } ] } ] }, "requestPendingApproval": { "summary": "Request pending approval\n", "description": "Example response for a request that is pending approval.\n", "value": { "certificate_request_id": "1a4e7b7b-03cf-40ff-a93c-41cc0edf220c", "status": "PENDING_APPROVAL" } } } } }