Add ACME credentials

POST
https://one.digicert.com/iot/api/v1/acme-authentication

Use this endpoint to add ACME credentials to your IoT Device Manager account and assign them to an enrollment profile that supports the ACME enrollment method.

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 IoT Device Manager account.

Adding ACME credentials

This endpoint supports two options for adding ACME credentials:

  • 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.
  • Create a new key identifier (KID) and keyed-hash message authentication code (HMAC).
    Use these credentials to register your IoT Device Manger account with an ACME client that supports external account binding.

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.

Assigning ACME credentials to an enrollment profile

When 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:

  • Limit how many times the credentials can be used to request a certificate with the enrollment profile.
  • Define start and end dates for when the credentials can be used with the enrollment profile.
  • Define values that certificate fields must contain when using the credentials to request a certificate with the enrollment profile.

Example requests and responses

cURL (New EAB credentials)
curl --request POST 'https://one.digicert.com/iot/api/v1/acme-authentication' \
--header 'x-api-key: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Example ACME Credentials",
  "description": "Test",
  "account_id": "f33847ce-cdea-4331-b106-027bb100892e",
  "enrollment_profile": "IOT_36b9f4e8-d4ab-417b-957b-2b88f2cc79b1",
  "external_account_binding": true,
  "usage_limit": 10,
  "start_date": "2021-03-01",
  "end_date": "2021-05-01",
  "registered_values": [
    {
      "certificate_field": "subject.common_name",
      "matcher": "equals",
      "value": "example1"
    },
    {
      "certificate_field": "subject.organization_unit",
      "matcher": "equals",
      "value": "example2"
    }
  ]
}'
cURL (Upload public key)
curl --request POST 'https://one.digicert.com/iot/api/v1/acme-authentication' \
--header 'x-api-key: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Example",
  "account_id": "f33847ce-cdea-4331-b106-027bb100892e",
  "authentication_pem": "-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApaBsbmUtChNjZA3C/39vzwF3qViD/myP9JbdVFktv2c1zK+GLA2xdC498yv0ZIboFehk+B1fi1WrswK3TA7ZPpZy6uwN+40aL0pxD0c4XM/7KwPRHHxVzsIHxx4fZZxgvYO9ew0pqNOXuYg8YanjExy2k8A81ICWsPNKMyW6ug/0mu9lKBI3dX11669YIgndSdidIdAHOUDCt/TNbHQgx7tGJ+CfHZl0gFe0G1SbXuyRvzFXEW6izPYPxc6PxKAtPdLn41tl9q0WiQbXFgCo4Hvl+oXkP2CLn8fpXkoHfyfJAcfqzqu7LWEo0Me5962x10Qhzy42D+Uwt5GoJ5U7zQIDAQAB-----END PUBLIC KEY-----",
  "enrollment_profile": "IOT_36b9f4e8-d4ab-417b-957b-2b88f2cc79b1",
  "usage_limit": 10,
  "start_date": "2021-02-25",
  "end_date": "2021-05-17",
  "registered_values": [
    {
      "certificate_field": "subject.common_name",
      "matcher": "equals",
      "value": "example1"
    },
    {
      "certificate_field": "subject.organization_unit",
      "matcher": "equals",
      "value": ["example1", "example2"]
    }
  ]
}'
201 (New credentials)
{
  "id": "9b71331a-bf8d-4da2-8786-cad5744b24f5",
  "name": "Example ACME Credentials",
  "description": "Test",
  "account_id": "f33847ce-cdea-4331-b106-027bb100892e",
  "status": "ACTIVE",
  "created_at": "2021-02-18T21:02:15.285249Z",
  "hmac_key": "qfzrHUyEYCqyrQPMfSLR9i7zEYhnERy4jbqO4y0yQ2PUo7J8JRzuwKCCi9FJW63ytu58JN9oQK0WovAZULu74Q",
  "external_account_binding": true,
  "account_bind": false
}
201 (Existing public key)
{
  "id": "8165f313-6883-4202-bd80-083e4a59a718",
  "name": "acme_creds_33",
  "description": "Test",
  "account_id": "f33847ce-cdea-4331-b106-027bb100892e",
  "authentication_pem": "-----BEGIN CERTIFICATE----- MIIEtjCCA56gAwIBAgIUMgAd9h294m6qt2No9+BIB3ZCeqQwDQYJKoZIhvcNAQEL BQAwgaYxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJVVDEPMA0GA1UEBxMGRHJhcGVy MSMwIQYDVQQJExo5MDcgRWFzdCBTYXBwaGlyZSBIaWxsIFdheTEjMCEGA1UEERMa OTA3IEVhc3QgU2FwcGhpcmUgSGlsbCBXYXkxETAPBgNVBAoTCGpUZXN0T3JnMRww GgYDVQQDExNqVGVzdE9yZyBJc3N1aW5nIENBMB4XDTIxMDIxODIwNDIwMVoXDTIx MDQzMDIxMjQxMlowMTELMAkGA1UEBhMCVVMxETAPBgNVBAoTCERpZ2lDZXJ0MQ8w DQYDVQQDDAZUZXN0XzEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCy pO2sk/wjS6VA1kiwI1JdYKLlQuK4wPP9xnEoJblATEsNmcpcpVQ8wk88AOYuoB3C iaoLKnDYrPm83/V9/Nu+Jf5j7I8wBeQBd0x208zGRxp38ED6OHcOmJUdQRmh7p7y DCCUnYAgpS4NpSF5xkVGBFjBiCcBZFw25/RiRu1II3wdbfuUs5NOlqtPE1YwaOzc OJUcGtt+29UUa2jTk0x20Psvn6pzhNel3Nk1H4GgJ6zIHXaJuztgNY8Ihp1NigNP r0xDBr51urwkXxgsPSjt7nq5MJGJpm14aTX1yiIU8Wc7d5w1PVuJNJSmoYuWeF+5 DIUcx1CPYkzqzS4+4R5xAgMBAAGjggFOMIIBSjAMBgNVHRMBAf8EAjAAMB0GA1Ud DgQWBBTQwEodyhXq4j1E0G0CkHAuRNdrzDAfBgNVHSMEGDAWgBQ9RN0/16h9aTRn VuJwhlaah8glEzAOBgNVHQ8BAf8EBAMCBaAwFgYDVR0lAQH/BAwwCgYIKwYBBQUH AwEwgYcGCCsGAQUFBwEBBHsweTAuBggrBgEFBQcwAYYiaHR0cDovL29jc3Auc3Rh Z2Uub25lLmRpZ2ljZXJ0LmNvbTBHBggrBgEFBQcwAoY7aHR0cDovL2NhY2VydHMu c3RhZ2Uub25lLmRpZ2ljZXJ0LmNvbS9qVGVzdE9yZ0lzc3VpbmdDQS5jcnQwSAYD VR0fBEEwPzA9oDugOYY3aHR0cDovL2NybC5zdGFnZS5vbmUuZGlnaWNlcnQuY29t L2pUZXN0T3JnSXNzdWluZ0NBLmNybDANBgkqhkiG9w0BAQsFAAOCAQEAEc0dvXfb BJ6+iwShuDG4YWdQwL/UJtFQSIFO0x0QK7ZTg4e094IViUDAYpNQ34cJSIu3S40M e1Z4eKZUtRYw0bbSQvDdVvbz6eY4hJy7kkRwOF0c0ZCNBXLYjZejxPYYgh/WIIkW WcuiqN4UMyRNTM/nVrSz1hZm9+NPbYD9G/fWPh3fwKRoUEULQma7FnuFSDvNyliW d/lqIy1U2IlfLnBO9e5l9M6b9HO1uqZit3kxR5AVlq7cBxHpclWLGSlI2zHcGgwr IhTe3JEY7Sq3AIa2mUPVL8VbML/ZI75rWmQfBkU7O9bDTkOa4esuVWxXQQs99Pos y6ScEbsgeI9Qig== -----END CERTIFICATE-----",
  "authentication_type": "certificate",
  "thumbprint": "9e00a421268a1e814805cb0571a157d2fdbd9b48a02286c77d4e76110727727d",
  "status": "ACTIVE",
  "created_at": "2021-02-18T20:43:01.850786Z",
  "key_type": "RSA",
  "rsa_key_size": 2048,
  "key_description": "RSA 2048",
  "certificate_common_name": "Test_1",
  "issuer_common_name": "jTestOrg Issuing CA",
  "external_account_binding": false,
  "account_bind": true,
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsqTtrJP8I0ulQNZIsCNS\nXWCi5ULiuMDz/cZxKCW5QExLDZnKXKVUPMJPPADmLqAdwomqCypw2Kz5vN/1ffzb\nviX+Y+yPMAXkAXdMdtPMxkcad/BA+jh3DpiVHUEZoe6e8gwglJ2AIKUuDaUhecZF\nRgRYwYgnAWRcNuf0YkbtSCN8HW37lLOTTparTxNWMGjs3DiVHBrbftvVFGto05NM\ndtD7L5+qc4TXpdzZNR+BoCesyB12ibs7YDWPCIadTYoDT69MQwa+dbq8JF8YLD0o\n7e56uTCRiaZteGk19coiFPFnO3ecNT1biTSUpqGLlnhfuQyFHMdQj2JM6s0uPuEe\ncQIDAQAB\n-----END PUBLIC KEY-----\n"
}

Request parameters

Name Req/Opt Type Description
name required string Unique name for the credentials.
Character limit: 255
description optional string Custom description of the credentials.
Character limit: 255
account_id required string Your account ID.
Character limit: 36
To get your account ID, sign in to your IoT Device Manager account.
external_account_binding optional bool 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
authentication_pem optional* string 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.
enrollment_profile optional string ID of an enrollment profile to assign the credentials. Profile must support the ACME enrollment method.
Character limit: 40
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 IoT Device Manager account.
usage_limit optional int Number of times the credentials can be used to request a certificate with the assigned enrollment_profile.
Default: No limit if not provided.
start_date optional string Start date for the period of time during which you can use the credentials with the assigned enrollment_profile.
Format: YYYY-MM-DD
Default: No limit if not provided.
end_date optional string End date for the period of time during which you can use the credentials with the assigned enrollment profile.
Format: YYYY-MM-DD
Default: No limit if not provided.
registered_values optional array 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 field values for requests that use these credentials, omit the registered_values object from your request.
.. certificate_field required string Name of a certificate field to validate when using the credentials.
Possible values: See Certificate fields.
.. matcher required 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 Key identifier (KID) for external account binding.
name string Unique name for the credentials.
Character limit: 255
description string Custom description of the credentials.
Character limit: 255
account_id string ID of the account the credentials belong to.
Character limit: 36
authentication_pem string PEM-encoded data for the uploaded certificate or public key.
authentication_type string Authentication type of the uploaded PEM data.
Possible values: certificate or public_key
thumbprint string Thumbprint of the uploaded certificate or public key.
status string ACME credential status.
Possible values: ACTIVE, DISABLED, or DELETED. Newly added credentials have a status of ACTIVE.
created_at string Date and time (UTC) the credentials were added.
Format: YYYY-MM-DDThh:mm:ss.sTZD
key_type string Key type of the uploaded certificate or public key.
Possible values: RSA or EC
rsa_key_size int If key_type is RSA, returns the key size of the uploaded certificate or public key.
ecdsa_curve string If key_type is EC, returns the ECDSA curve for the uploaded certificate or public key.
key_description string Description of the uploaded certificate or public key.
certificate_common_name string Common name on the uploaded certificate.
issuer_common_name string Common name on the intermediate certificate authority (ICA) that issued the uploaded certificate.
hmac_key string HMAC key for external account binding.
external_account_binding bool 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.
account_bind bool Returns true when the key identifier and ACME key credentials have been registered with an ACME client.
public_key_pem string PEM-encoded data for the uploaded public key.

Certificate fields

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