Create enrollment passcode

POST
https://one.digicert.com/iot/api/v1/enrollment-profile/{{enrollment_profile_id}}/passcode

Use this endpoint to create a unique passcode for authenticating orders associated with an enrollment profile in your account.

Replace {{enrollment_profile_id}} in the request URL with the ID of the enrollment profile to create the passcode for. You can create multiple passcodes for a single enrollment profile, each with a different validity period or usage limit.

You can only create passcodes for enrollment profiles that use EST, SCEP, or CMPv2 enrollment methods.

Example requests and responses

cURL
curl -X POST 'https://one.digicert.com/iot/api/v1/enrollment-profile/IOT_06ddbdc0-23d7-4ba2-8d3b-253b6d456044/passcode' \
-H 'x-api-key: {{api_key}}' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{
	"name": "passcode_name",
	"description": "A passcode we created for the API documentation.",
	"passcode_length": 20,
	"usage_limit": 2000,
	"validity_period": {
		"from": "2020-12-15",
		"to": "2021-05-15"
	},
    "registered_values": [
        {
            "certificate_field": "subject.common_name",
            "value": "example.com"
        },
        {
            "certificate_field": "subject.organization_unit",
            "value": ["Unit1", "Unit3"]
        }
    ]
 }'
Python
import requests

url = "https://one.digicert.com/iot/api/v1/enrollment-profile/IOT_06ddbdc0-23d7-4ba2-8d3b-253b6d456044/passcode"

payload = "{\n\t\"name\": \"passcode_name\",\n\t\"description\": \"A passcode we created for the API documentation.\",\n\t\"passcode_length\": 20,\n\t\"usage_limit\": 2000,\n\t\"validity_period\": {\n\t\t\"from\": \"2020-12-15\",\n\t\t\"to\": \"2021-05-15\"\n\t},\n    \"registered_values\": [\n        {\n            \"certificate_field\": \"subject.common_name\",\n            \"value\": \"example.com\"\n        },\n        {\n            \"certificate_field\": \"subject.organization_unit\",\n            \"value\": [\"Unit1\", \"Unit3\"]\n        }\n    ]\n }"
headers = {
  'x-api-key': '{{api_key}}',
  'Content-Type': 'application/json;charset=UTF-8',
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))
Go
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://one.digicert.com/iot/api/v1/enrollment-profile/IOT_06ddbdc0-23d7-4ba2-8d3b-253b6d456044/passcode"
  method := "POST"

  payload := strings.NewReader("{\n	\"name\": \"passcode_name\",\n	\"description\": \"A passcode we created for the API documentation.\",\n	\"passcode_length\": 20,\n	\"usage_limit\": 2000,\n	\"validity_period\": {\n		\"from\": \"2020-12-15\",\n		\"to\": \"2021-05-15\"\n	},\n    \"registered_values\": [\n        {\n            \"certificate_field\": \"subject.common_name\",\n            \"value\": \"example.com\"\n        },\n        {\n            \"certificate_field\": \"subject.organization_unit\",\n            \"value\": [\"Unit1\", \"Unit3\"]\n        }\n    ]\n }")

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("x-api-key", "{{api_key}}")
  req.Header.Add("Content-Type", "application/json;charset=UTF-8")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}
NodeJS
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://one.digicert.com/iot/api/v1/enrollment-profile/IOT_06ddbdc0-23d7-4ba2-8d3b-253b6d456044/passcode',
  'headers': {
    'x-api-key': '{{api_key}}',
    'Content-Type': 'application/json;charset=UTF-8',
  },
  body: "{\n\t\"name\": \"passcode_name\",\n\t\"description\": \"A passcode we created for the API documentation.\",\n\t\"passcode_length\": 20,\n\t\"usage_limit\": 2000,\n\t\"validity_period\": {\n\t\t\"from\": \"2020-12-15\",\n\t\t\"to\": \"2021-05-15\"\n\t},\n    \"registered_values\": [\n        {\n            \"certificate_field\": \"subject.common_name\",\n            \"value\": \"example.com\"\n        },\n        {\n            \"certificate_field\": \"subject.organization_unit\",\n            \"value\": [\"Unit1\", \"Unit3\"]\n        }\n    ]\n }"

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
201 Passcode created
{
    "name": "passcode_name",
    "description": "A passcode we created for the API documentation.",
    "validity_period": {
        "from": "2020-12-15",
        "to": "2021-05-15"
    },
    "passcode_length": 20,
    "usage_limit": 2000,
    "status": "ACTIVE",
    "registered_values": [
        {
            "certificate_field": "subject.common_name",
            "matcher": "equals",
            "value": "example.com",
            "multiple": false
        },
        {
            "certificate_field": "subject.organization_unit",
            "matcher": "equals",
            "value": [
                "Unit1",
                "Unit3"
            ],
            "multiple": true
        }
    ],
    "id": "2ecc7a75-7b5e-4f40-9fe7-beafa716f255",
    "enrollment_profile": {
        "id": "IOT_06ddbdc0-23d7-4ba2-8d3b-253b6d456044",
        "name": "SCEP"
    },
    "device_profile": {
        "id": "6a7dddf4-15d9-4db4-898d-9d9f4e9ed9f7",
        "name": "jDeviceProfile"
    },
    "division": {
        "id": "ee64ec0f-510f-4561-896e-2d5fe935690e",
        "name": "division_name"
    },
    "account_id": "f33847ce-cdea-4331-b106-027bb100892e",
    "passcode": "H2QDEBTWCh3qe5gg7AWI",
    "created_at": "2020-10-02T21:16:02Z",
    "number_of_usage": 0
}
400 Invalid input
{
    "errors": [
        {
            "code": "invalid_input",
            "message": "name: must not be blank"
        }
    ]
}
401 Authentication error
// Access denied due to invalid API key. 
{
    "errors": [
        {
            "code": "access_denied",
            "message": "Access denied"
        }
    ]
}
403 Authorization error
// Access denied because the account does not have permission to manage IoT enrollment profiles.
{
    "errors": [
        {
            "code": "access_denied",
            "message": "Access denied"
        }
    ]
}

Request parameters

Name Opt/Req Type Description
name required string Name of your choosing for the passcode. Should be unique within the enrollment profile.
Character limit: 64
description optional string Custom passcode description.
Character limit: 255
passcode_length optional integer Number of characters in the passcode.
Range: 20 - 64
Default: 27
Note: For enrollment profiles using the SCEP enrollment method, passcode length is fixed at 20 characters.
usage_limit optional integer Number of times the passcode can be used.
If not provided, the passcode does not have a usage limit.
validity_period optional object 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.
.. from optional string Start date of passcode validity period.
Format: YYYY-MM-DD
If not provided, the passcode can be used immediately.
.. to optional string End date of passcode validity period.
Format: YYYY-MM-DD
If not provided, the passcode does not expire.
registered_values optional array 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.
.. certificate_field required string Name of a certificate field to validate when using this passcode.
Allowed values: See Certificate fields that support registered values.
.. matcher optional string Operator to use when comparing the value of the certificate field to the registered value.
Allowed values: equals
.. value required string/array 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.

Response parameters

Name Type Description
id string Unique ID created for the passcode.
name string Passcode name.
description string Passcode description.
account_id string ID of the account that created the passcode.
passcode string Unique passcode.
passcode_length integer Passcode length.
status string Passcode status.
Possible values: ACTIVE, DISABLED, or DELETED. Newly created passcodes are expected to have a status of ACTIVE.
number_of_usage int Number of times the passcode has been used.
usage_limit int Number of times the passcode can be used.
validity_period object Object that defines the period of time during which the passcode can be used.
.. from string Start date of passcode validity period.
.. to string End date of passcode validity period.
created_at string Date and time (UTC) the passcode was created
device_profile object Details about the device profile associated with the passcode.
.. id string Device profile ID.
.. name string Device profile name.
division object Details about the division associated with the passcode.
.. id string Division ID.
.. name string Division name.
enrollment_profile object Details about the enrollment profile associated with the passcode.
.. id string Enrollment profile ID.
.. name string Enrollment profile name.
registered_values array List of objects with details about the certificate fields that are validated when using this passcode.
Only returned for requests that include the registered_values request parameter.
.. certificate_field string Name of a certificate field that is validated when using this passcode.
Possible values: See Certificate fields that support registered values.
.. matcher string Operator used when comparing the value of the certificate field to the registered values.
Possible values: equals
.. value string/array The value or list of values that are compared with the value of the chosen certificate_field.
.. multiple bool Returns true when the data type of the certificate field is an array. Otherwise, false.

Certificate fields that support registered values

Field Type
subject.common_name string
subject.organization_name string
subject.organization_unit array
subject.country string
subject.state string
subject.locality string
subject.street_address array
subject.postal_code string
subject.email string
challenge_password string