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'))

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

Example requests and responses

Request parameters

Response parameters

Certificate fields that support registered values

简介