Standard Issuance Protocols (API)

• ACME Certificate Issuance
  • ACME Directories
  • Get ACME EAB Binding Token
  • List Unused ACME EAB Binding Tokens
  • Delete Unused ACME EAB Binding Tokens
  • Get ACME Configuration
  • Set ACME Configuration
  • List ACME Account Keys
  • Get ACME Account Info
  • Update ACME Account Info
• EST - Certificate Issuance EnterpriseEnterprise
  • EST Protocol Paths EnterpriseEnterprise
  • Read EST Configuration EnterpriseEnterprise
  • Set EST Configuration EnterpriseEnterprise
• CMPv2 - Certificate Management Protocol (v2) EnterpriseEnterprise
  • CMPv2 Protocol Paths EnterpriseEnterprise
  • Read CMPv2 Configuration EnterpriseEnterprise
  • Set CMPv2 Configuration EnterpriseEnterprise
• SCEP - Simple Certificate Enrollment Protocol EnterpriseEnterprise
  • SCEP Protocol Paths EnterpriseEnterprise
  • Read SCEP Configuration EnterpriseEnterprise
  • Set SCEP Configuration EnterpriseEnterprise

ACME certificate issuance

Starting with Vault 1.14, Vault supports the ACME certificate lifecycle management protocol for issuing and renewing leaf server certificates.

In order to use ACME, a cluster path must be set and ACME must be enabled in its configuration with the required headers enabled on the mount tuning.

Using ACME with a role requires no_store=false to be set on the role; this allows the certificate to be stored and later fetched through the ACME protocol.

ACME directories

Vault PKI supports the following ACME directories, providing different restrictions around usage (defaults, a specific issuer and/or a specific role). To interact with these directories, specify the directory URL in an ACME client. For example, with the EFF's CertBot:

$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory ...

These endpoints are unauthenticated from a Vault authentication model, but internally authenticated via the ACME protocol.

When a role is not explicitly specified, behavior is specified by the default_directory_policy in the ACME configuration. These directories can also be forbidden by setting that policy as forbid. If the policy is sign-verbatim then any identifier for which the client can prove ownership of will be issued for. This is similar to using the Sign Verbatim endpoint, but with additional verification that the client has proven ownership (within the ACME protocol) of the requested certificate identifiers. When external-policy is specified as the default value, the Certificate Issuance External Policy Service (CIEPS)EnterpriseEnterprise is used for validating and templating the certificate instead of a role; ACME's challenge validation is still enforced. An optional policy name can be specified by using external-policy:policy. Roles are not used when CIEPS is used.

ACME challenge types

Vault supports the following ACME challenge types presently:

• http-01, supporting both dns and ip identifiers.
• dns-01, supporting dns identifiers including wildcards.
• tls-alpn-01, supporting only non-wildcard dns identifiers.

A custom DNS resolver used by the server for looking up DNS names for use with both mechanisms can be added via the ACME configuration.

ACME external account bindings

ACME External Account Binding (EAB) Policy can enforce that clients need to have a valid external account binding to Vault. Before registering a new account, an authenticated Vault client will need to fetch a new EAB token. This returns two values: a key identifier and an HMAC key used by the ACME client to authenticate with EAB. For example:

$ vault write -f /pki/acme/new-eab
$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory \
                   --eab-kid <id> --eab-hmac-key <hmac-key>

With or without EAB, requests from the ACME client are not authenticated using traditional Vault authentication, but are instead authenticated through the ACME protocol. With EAB however, a Vault authenticated client will have to fetch an EAB token and pass it to the ACME client for use on the initial registration: this binds the ACME client's registration to an authenticated Vault endpoint, but not further to the client's entity or other information.

ACME accounts

ACME Accounts are created specific to a particular directory and are not portable across Performance Secondary clusters.

ACME required headers

ACME requires the following response headers (allowed_response_headers) to be specified by mount tuning:

• Replay-Nonce
• Link
• Location

On an existing mount, these can be specified by running the following command:

$ vault secrets tune -allowed-response-headers=Location -allowed-response-headers=Replay-Nonce \
                     -allowed-response-headers=Link \
                     pki/

Get ACME EAB binding token

This endpoint returns a new ACME binding token. The id response field can be used as the key identifier and the key response field be used as the EAB HMAC key in the ACME Client.

Each call to this endpoint will generate and return a new EAB binding token that is linked to the specific ACME directory it resides under. EAB tokens are not usable across different ACME directories.

Parameters

No parameters.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/pki/acme/new-eab

Sample response

{
  "data": {
    "created_on": "2023-05-24T14:33:00-04:00",
    "id": "bc8088d9-3816-5177-ae8e-d8393265f7dd",
    "key_type": "hs",
    "acme_directory": "acme/directory",
    "key": "MHcCAQE... additional data elided ...",
  }
}

List unused ACME EAB binding tokens

This endpoint returns a list of all unused ACME binding tokens; once used, they will be removed from this list.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/pki/eab

Sample response

{
  "data": {
    "key_info": {
      "bc8088d9-3816-5177-ae8e-d8393265f7dd": {
        "created_on": "2023-05-24T14:33:00-04:00",
        "key_type": "hs",
        "acme_directory": "acme/directory"
      }
    },
    "keys": [
      "bc8088d9-3816-5177-ae8e-d8393265f7dd"
    ]
  }
}

Delete unused ACME EAB binding tokens

This endpoint allows the deletion of an unused ACME binding token.

Parameters

• key_id (string: <required>) - The id of the EAB binding token to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/pki/eab/bc8088d9-3816-5177-ae8e-d8393265f7dd

Get ACME configuration

This endpoint allows reading of the current ACME server configuration used by this mount.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/acme

Sample response

{
  "data": {
    "allowed_issuers": [
      "*"
    ],
    "allowed_roles": [
      "*"
    ],
    "default_directory_policy": "sign-verbatim",
    "dns_resolver": "",
    "eab_policy": "not-required",
    "enabled": true,
    "max_ttl": 776000
  },
}

Set ACME configuration

This endpoint allows setting the ACME server configuration used by this mount.

Parameters

• allowed_issuers (list: ["*"]) - Specifies a list issuers allowed to issue certificates via explicit ACME paths. If an allowed role specifies an issuer outside this list, it will be allowed. The default value * allows every issuer within the mount.

• allow_role_ext_key_usage (bool: false) - whether the ExtKeyUsage field from a role is used, defaults to false meaning that certificate will be signed with ServerAuth.

• allowed_roles (list: ["*"]) - Specifies a list of roles allowed to issue certificates via explicit ACME paths. The default value * allows every role within the mount to be used. If the default_directory_policy specifies a role, it must be allowed under this configuration.

• default_directory_policy (string: "sign-verbatim") - Specifies the behavior of the default ACME directory. Can be forbid, sign-verbatim or a role given by role:<role_name>. If a role is used, it must be present in allowed_roles.

• dns_resolver (string: "") - An optional overriding DNS resolver to use for challenge verification lookups. When not specified, the default system resolver will be used. This allows domains on peered networks with an accessible DNS resolver to be validated.

• eab_policy (string: "not-required") - Specified policy to enforce around External Account Bindings (EABs). The allowed values are:

  • not-required, where EABs are not enforced but are validated if specified.

  • new-account-required, where new accounts are required to have EAB but existing accounts can still be used.

  • always-required, where all accounts regardless of age are required to have EABs set.

• enabled (bool: false) - Whether ACME is enabled on this mount. When ACME is disabled, all requests to ACME directory URLs will return 404.

• max_ttl (string: "") - Specifies the maximum Time To Live provided as a string duration with time suffix. Hour is the largest suffix. If not set, defaults to the previous hard-coded behavior of 90 days (2160 hours).

Sample payload

{
    "enabled": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/config/acme

Sample response

{
  "data": {
    "allowed_issuers": [
      "*"
    ],
    "allowed_roles": [
      "*"
    ],
    "default_directory_policy": "sign-verbatim",
    "dns_resolver": "",
    "eab_policy": "not-required",
    "enabled": true
  }
}

List ACME account keys

The ListAcmeAccountKeys endpoint returns a list of ACME account key identifiers.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid

Sample response

{
  "data": {
    "keys": [
      "2ea9859a-eba8-ff24-cd03-2a51639fc7d5"
    ]
  }
}

Get ACME account info

The GetAcmeAccountInfo endpoint returns account information, including orders and certificate details, for the provided ACME account key.

Path parameters

• key_id (string: <required>) - ID of the target ACME account.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid/2ea9859a-eba8-ff24-cd03-2a51639fc7d5

Sample response

{
  "data": {
    "contacts": null,
    "created_time": "2024-12-12T12:55:50-05:00",
    "directory": "acme/",
    "eab": {
      "created_time": "2024-12-12T12:55:29-05:00",
      "directory": "acme/",
      "eab_id": "24c0673a-df53-0671-a628-e7b9c995485c",
      "key_type": "hs"
    },
    "key_id": "2ea9859a-eba8-ff24-cd03-2a51639fc7d5",
    "orders": [
      {
        "cert_expiry": "2024-12-13T17:55:28Z",
        "cert_serial_number": "4a:6f:d0:f7:13:55:f7:c9:19:82:fc:34:69:67:77:2e:58:27:02:8b",
        "identifiers": [
          "testing.dadgarcorp.com"
        ],
        "order_expiry": "2024-12-13T12:56:04-05:00",
        "order_id": "90699994-8863-571c-26b0-46755e0db351",
        "status": "valid"
      }
    ],
    "revoked_time": "",
    "status": "valid"
  },
}

Update ACME account info

The UpdateAcmeAccountInfo endpoint revokes or re-enables an ACME account and returns the account details excluding order or certificate details.

Path parameters

• key_id (string: <required>) - ID of the target ACME account.

Parameters

• status (string: <required>) - The new account status. Must be one of: revoked, valid.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid/2ea9859a-eba8-ff24-cd03-2a51639fc7d5

Sample response

{
  "data": {
    "contacts": null,
    "created_time": "2024-12-12T12:55:50-05:00",
    "directory": "acme/",
    "eab": {
      "created_time": "2024-12-12T12:55:29-05:00",
      "directory": "acme/",
      "eab_id": "24c0673a-df53-0671-a628-e7b9c995485c",
      "key_type": "hs"
    },
    "key_id": "2ea9859a-eba8-ff24-cd03-2a51639fc7d5",
    "revoked_time": "2024-12-12T12:59:02-05:00",
    "status": "revoked"
  },
}

EST Certificate issuance EnterpriseEnterprise

Within Vault Enterprise, support can be enabled for the EST (Enrollment over Secure Transport) protocol for issuing and renewing leaf certificates.

EST Protocol Paths EnterpriseEnterprise

These are the EST protocol API paths currently supported from Vault's authentication point of view. Note that the cacerts endpoint is unauthenticated.

Read EST Configuration EnterpriseEnterprise

This endpoint fetches the current EST configuration.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/est

Sample response

{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_7fe0c1cc",
        "cert_role": "est-ca"
      },
      "userpass": {
        "accessor": "auth_userpass_2b333949"
      }
    },
    "default_mount": true,
    "default_path_policy": "sign-verbatim",
    "enable_sentinel_parsing": true,
    "enabled": true,
    "label_to_path_policy": {
      "test-label": "role:est-clients"
    },
    "last_updated": "2024-01-31T10:45:22-05:00"
  }
}

Set EST Configuration EnterpriseEnterprise

This endpoint will update EST related configuration, returning the updated values as a response along with an updated last_updated field.

Parameters

• enabled (bool: false) - Specifies whether EST is enabled or not.

• default_mount (bool: false) - Should this mount register the default .well-known/est URL path. Only a single mount can enable this across a Vault cluster

• default_path_policy (string: "") - Required to be set if default_mount is enabled. Specifies the behavior for requests using the default EST label. Can be sign-verbatim or a role given by role:<role_name>.

• label_to_path_policy (map[string]string: "") - Configures a pairing of an EST label with the redirected behavior for requests hitting that role. The path policy can be sign-verbatim or a role given by role:<role_name>. Labels must be unique across Vault cluster, and will register .well-known/est/<label> URL paths.

• authenticators (map[string]map[string]string: "") - Specifies the mount accessors EST should delegate authentication requests. Map keys can be either cert or userpass, with associated maps containing the key accessor with a value containing the auth mount's accessor. For the cert type, an optional key cert_role parameter is supported which will be passed as the name parameter during certificate authentication attempts.

• enable_sentinel_parsing (bool: false) - Parse out fields from the provided CSR making them available for Sentinel policies.

• audit_fields (list: ["common_name", "alt_names", "ip_sans", "uri_sans"]) - Fields parsed from the CSR that appear in the audit and can be used by sentinel policies. Allowed values are csr, common_name, alt_names, ip_sans, uri_sans, other_sans, signature_bits, exclude_cn_from_sans, ou, organization, country, locality, province, street_address, postal_code, serial_number, use_pss, key_type, key_bits, add_basic_constraints

Sample Payload

{
  "enabled": true,
  "default_mount": true,
  "label_to_path_policy": {
    "test-label": "role:est-clients",
    "sign-all": "sign-verbatim"
  },
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_0f1df449",
      "cert_role": "cert1"
    },
    "userpass": {
      "accessor": "auth_userpass_b2b08fac"
    }
  },
  "enable_sentinel_parsing": true,
  "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/config/est

Sample response

{
  "data": {
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_0f1df449",
        "cert_role": "cert1"
      },
      "userpass": {
        "accessor": "auth_userpass_b2b08fac"
      }
    },
    "default_mount": true,
    "default_path_policy": "sign-verbatim",
    "enabled": true,
    "label_to_path_policy": {
      "sign-all": "sign-verbatim",
      "test-label": "role:est-clients"
    },
    "last_updated": "2024-02-02T10:49:20-05:00"
  }
}

CMPv2 Certificate issuance EnterpriseEnterprise

Within Vault Enterprise, support can be enabled for the CMPv2 (Certificate Management Protocol) protocol for issuing and renewing leaf certificates.

CMPv2 Protocol Paths EnterpriseEnterprise

These are the CMP protocol API paths currently supported from Vault's authentication point of view.

The Default Path Policy is specified in the CMPv2 configuration. When a role is not explicitly specified within the path, the behavior is specified by the default_path_policy field.

Read CMPv2 Configuration EnterpriseEnterprise

This endpoint fetches the current CMPv2 configuration.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/cmp

Sample response

{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "default_path_policy": "role:example-role",
    "disabled_validations": [],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_7fe0c1cc",
        "cert_role": "cmp-ca"
      }
    },
    "enable_sentinel_parsing": true,
    "enabled": true,
    "last_updated": "2024-01-31T10:45:22-05:00"
  }
}

Set CMPv2 Configuration EnterpriseEnterprise

This endpoint will update CMPv2 related configuration, returning the updated values as a response along with an updated last_updated field.

Parameters

• enabled (bool: false) - Specifies whether CMPv2 is enabled or not.

• authenticators (map[string]map[string]string: "") - Specifies the mount accessors CMPv2 should delegate authentication requests. Map key can only be cert, with associated value containing the key accessor with a value containing the auth mount's accessor. An optional key cert_role parameter is supported which will be passed as the name parameter during certificate authentication attempts.

• default_path_policy (string: required): Specify the default issuance policy when the non role based cmp path is called. Must be set to either sign-verbatim (to issue via the sign-verbatim function) or role: followed by the name of a configured role.

• enable_sentinel_parsing (bool: false) - Parse out fields from the provided CSR making them available for Sentinel policies.

• audit_fields (list: ["common_name", "alt_names", "ip_sans", "uri_sans"]) - Fields parsed from the CSR that appear in the audit and can be used by sentinel policies. Allowed values are csr, common_name, alt_names, ip_sans, uri_sans, other_sans, signature_bits, exclude_cn_from_sans, ou, organization, country, locality, province, street_address, postal_code, serial_number, use_pss, key_type, key_bits, add_basic_constraints

• disabled_validations (list: []) - Checks to skip during request validation. Possible values are DisableMatchingKeyIdValidation, and 'DisableCertTimeValidation'. DisableMatchingKeyIdValidation disables the check that sender key ID in the request header needs to match the subject public key ID in the signing certificate. DisableCertTimeValidation disables the not before/not after verifications within the signing certificate. Disabling any validation is highly discouraged.

Sample Payload

{
  "enabled": true,
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_0f1df449",
      "cert_role": "cert1"
    },
   "default_path_policy": "sign-verbatim",
   "disabled_validations": ["DisableMatchingKeyIdValidation"],
   "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
   "enable_sentinel_parsing": true
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/config/cmp

Sample response

{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_0f1df449",
        "cert_role": "cert1"
      }
    },
    "default_path_policy": "sign-verbatim",
    "disabled_validations": ["DisableMatchingKeyIdValidation"],
    "enabled": true,
    "enable_sentinel_parsing": true,
    "last_updated": "2024-02-02T10:49:20-05:00"
  }
}

SCEP certificate issuance EnterpriseEnterprise

Vault Enterprise supports SCEP (Simple Certificate Enrollment Protocol) when issuing leaf certificates.

For a comprehensive overview of SCEP and how to configure it, refer to the SCEP documentation.

SCEP protocol paths EnterpriseEnterprise

Vault authentication supports the following SCEP protocol paths:

Read SCEP configuration EnterpriseEnterprise

Fetch the current SCEP configured for PKI.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/scep

Sample response

{
  "data": {
    "allowed_digest_algorithms": [
      "sha-256",
      "sha-384",
      "sha-512"
    ],
    "allowed_encryption_algorithms": [
      "aes128-cbc",
      "aes128-gcm",
      "aes256-cbc",
      "aes256-gcm"
    ],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_598b1030",
        "cert_role": "scep-ca"
      },
      "scep": {
        "accessor": "auth_scep_797d8401",
        "scep_role": ""
      }
    },
    "default_path_policy": "sign-verbatim",
    "enabled": true,
    "external_validation": {},
    "last_updated": "2025-05-26T09:59:24-04:00",
    "log_level" : "WARN",
    "restrict_ca_chain_to_issuer": true
  }
}

Set SCEP configuration EnterpriseEnterprise

Update SCEP related configuration for your PKI plugin. On success, Vault updates the last_updated field and returns the new configuration values. For a comprehensive overview of SCEP and how to configure it, refer to the SCEP documentation.

Parameters

• enabled (bool: false) - Specifies whether SCEP is enabled or not.

• default_path_policy (string: "") - Specifies the behavior for non-role-qualified SCEP requests. Must be a role given by role:<role_name> or sign-verbatim.

• authenticators (map[string]map[string]string: "") - Specifies the mount accessors to which SCEP should delegate authentication requests. Map keys can be any of the following:

  • scep - Associated value is a map containing configuration details for SCEP authentication. Associated subkeys:

    • accessor (required) - mount path for the authentication plugin.
    • scep_role (optional) - the name parameter passed during SCEP authentication attempts.

  • cert - Associated value is a map containing configuration details for certificate based authentication. Associated subkeys:

    • accessor (required) - mount path for the authentication plugin.
    • cert_role (optional) - the name parameter passed during certificate authentication attempts.

• allowed_encryption_algorithms ([]string) - the list of allowed encryption algorithms for SCEP requests. Can be any of:

  • des-cbc - DES encryption in CBC mode
  • 3des-cbc - 3DES encryption in CBC mode
  • aes128-cbc - AES-128 encryption in CBC mode
  • aes256-cbc - AES-256 encryption in CBC mode
  • aes128-gcm - AES-128 encryption in GCM mode
  • aes256-gcm - AES-256 encryption in GCM mode

• allowed_digest_algorithms ([]string) - the list of allowed digest algorithms for SCEP requests. May be any of: sha-1, sha-256, sha-384, sha-512

• restrict_ca_chain_to_issuer (bool: false) - whether to return the full CA chain within GetCACert responses. Set restrict_ca_chain_to_issuer to true to make your PKI configuration compatible with Microsoft Intune.

• log_level (string: "") - the log level to use for logging SCEP-specific requests. One of standard log levels: TRACE, DEBUG, INFO, WARN, ERROR, or use the empty string to reset to the vault-level default. (1.20.1+ only)

• external_validation (map[string]map[string]string: "") - a map specifying configuration for 3rd party validation of SCEP requests. Map keys can be any of the following:

  • intune - Associated value is a map containing configuration details to validate authentication requests with Microsoft Intune. Associated subkeys:

    • tenant_id (string: <required>) - Tenant ID for the Azure Active Directory organization. Overrides the AZURE_TENANT_ID environment variable.
    • client_id (string: <required or "MSI">) - Client ID for credentials used to invoke Azure APIs. Overrides the AZURE_CLIENT_ID environment variable.
    • client_secret (string: <required or "MSI">) - Client secret for credentials to invoke Azure APIs.. Overrides the AZURE_CLIENT_SECRET environment variable.
    • environment (string: "AzurePublicCloud") - Azure Cloud environment API endpoints to use for validation. Overrides the AZURE_ENVIRONMENT environment variable.

    All intune parameter values can use indirect value reference.

Sample Payload

{
  "enabled": true,
  "default_path_policy": "role:scep-clients",
  "authenticators": {
    "scep": {
      "accessor": "auth_scep_797d8401"
    },
    "cert": {
      "accessor": "auth_cert_598b1030",
      "cert_role": "scep-ca"
    }
  }
}

Sample response

{
  "data": {
    "allowed_digest_algorithms": [
      "sha-256",
      "sha-384",
      "sha-512"
    ],
    "allowed_encryption_algorithms": [
      "aes128-cbc",
      "aes128-gcm",
      "aes256-cbc",
      "aes256-gcm"
    ],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_598b1030",
        "cert_role": "scep-ca"
      },
      "scep": {
        "accessor": "auth_scep_797d8401",
        "scep_role": ""
      }
    },
    "default_path_policy": "role:scep-clients",
    "enabled": true,
    "external_validation": {},
    "last_updated": "2025-05-26T09:59:24-04:00",
    "restrict_ca_chain_to_issuer": false
  }
}