---
layout: api
page_title: PKI - Secrets Engines - Issuance Protocols
description: This is the API documentation for the issuance protocol support in Vault PKI.
---

# Standard Issuance Protocols (API)

- [ACME Certificate Issuance](#acme-certificate-issuance)
  - [ACME Directories](#acme-directories)
  - [Get ACME EAB Binding Token](#get-acme-eab-binding-token)
  - [List Unused ACME EAB Binding Tokens](#list-unused-acme-eab-binding-tokens)
  - [Delete Unused ACME EAB Binding Tokens](#delete-unused-acme-eab-binding-tokens)
  - [Get ACME Configuration](#get-acme-configuration)
  - [Set ACME Configuration](#set-acme-configuration)
- [EST - Certificate Issuance <EnterpriseAlert inline="true" />](#est-certificate-issuance)
  - [EST Protocol Paths <EnterpriseAlert inline="true" />](#est-protocol-paths)
  - [Read EST Configuration <EnterpriseAlert inline="true" />](#read-est-configuration)
  - [Set EST Configuration <EnterpriseAlert inline="true" />](#set-est-configuration)
- [CMPv2 - Certificate Management Protocol (v2) <EnterpriseAlert inline="true"/>](#cmpv2-certificate-issuance)
  - [CMPv2 Protocol Paths <EnterpriseAlert inline="true" />](#cmpv2-protocol-paths)
  - [Read CMPv2 Configuration <EnterpriseAlert inline="true" />](#read-cmpv2-configuration)
  - [Set CMPv2 Configuration <EnterpriseAlert inline="true" />](#set-cmpv2-configuration)

## ACME certificate issuance

Starting with Vault 1.14, Vault supports the [ACME certificate lifecycle
management protocol](https://datatracker.ietf.org/doc/html/rfc8555) for issuing
and renewing leaf server certificates.

In order to use ACME, a [cluster path](#set-cluster-configuration) must be
set and ACME must be [enabled in its configuration](#set-acme-configuration)
with the [required headers](#acme-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](https://certbot.eff.org/):

```
$ 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.

| Method | Path                                                               | Default Directory Policy   | Issuer                | Role          |
|:-------|:-------------------------------------------------------------------|:---------------------------|:----------------------|:--------------|
| `ACME` | `/pki/acme/directory`                                              | `sign-verbatim`            | `default`             | Sign-Verbatim |
| `ACME` | `/pki/acme/directory`                                              | `role:role_ref`            | Specified by the role | `:role_ref`   |
| `ACME` | `/pki/acme/directory`                                              | `external-policy(:policy)` | Specified by CIEPS    | CIEPS         |
| `ACME` | `/pki/issuer/:issuer_ref/acme/directory`                           | `sign-verbatim`            | `:issuer_ref`         | Sign-Verbatim |
| `ACME` | `/pki/issuer/:issuer_ref/acme/directory`                           | `role:role_ref`            | `:issuer_ref`         | `:role_ref`   |
| `ACME` | `/pki/roles/:role/acme/directory`                                  | (any)                      | Specified by the role | `:role`       |
| `ACME` | `/pki/issuer/:issuer_ref/roles/:role/acme/directory`               | (any)                      | `:issuer_ref`         | `:role`       |
| `ACME` | `/pki/external-policy(/:policy)/acme/directory`                    | (any)                      | Specified by CIEPS    | CIEPS         |
| `ACME` | `/pki/issuer/:issuer_ref/external-policy(/:policy)/acme/directory` | (any)                      | Specified by CIEPS    | CIEPS         |

When a role is not explicitly specified, behavior is specified by the
`default_directory_policy` in the [ACME configuration](#set-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](#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)<EnterpriseAlert inline="true" /> 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](#set-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](#get-acme-eab-binding-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.

~> Note: Enabling EAB is strongly recommended for public-facing Vault
   deployments. Use of the `VAULT_DISABLE_PUBLIC_ACME` environment variable
   can be used to enforce all ACME instances have EAB enabled.

#### 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](/vault/api-docs/system/mounts#tune-mount-configuration):

 - `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.

| Method | Path                                               |
|:-------|:---------------------------------------------------|
| `POST` | `/pki/acme/new-eab`                                |
| `POST` | `/pki/issuer/:issuer_ref/acme/new-eab`             |
| `POST` | `/pki/roles/:role/acme/new-eab`                    |
| `POST` | `/pki/issuer/:issuer_ref/roles/:role/acme/new-eab` |

#### 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.

| Method | Path       |
| :----- | :--------- |
| `LIST` | `/pki/eab` |

#### 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.

| Method   | Path               |
| :------- | :----------------- |
| `DELETE` | `/pki/eab/:key_id` |

#### 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.

| Method | Path               |
| :----- | :----------------- |
| `GET`  | `/pki/config/acme` |

#### 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.

| Method | Path               |
| :----- | :----------------- |
| `POST` | `/pki/config/acme` |

#### 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)](#acme-external-account-bindings).
   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
  }
}
```

## EST Certificate issuance <EnterpriseAlert inline="true" />

Within Vault Enterprise, support can be enabled for the
[EST (Enrollment over Secure Transport) protocol](https://datatracker.ietf.org/doc/html/rfc7030)
for issuing and renewing leaf certificates.

### EST Protocol Paths <EnterpriseAlert inline="true" />

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

@include 'pki-est-default-policy.mdx'

### Read EST Configuration <EnterpriseAlert inline="true" />

This endpoint fetches the current EST configuration.

| Method | Path             |
| :----- |:-----------------|
| `GET`  | `/pki/config/est` |

#### Sample request

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

#### Sample response

```json
{
  "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 <EnterpriseAlert inline="true" />

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

| Method | Path              |
|:-------|:------------------|
| `POST` | `/pki/config/est` |

#### 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](/vault/api-docs/auth/cert#name-6) 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

```json
{
  "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

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

#### Sample response

```json
{
  "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 <EnterpriseAlert inline="true" />

Within Vault Enterprise, support can be enabled for the
[CMPv2 (Certificate Management Protocol) protocol](https://datatracker.ietf.org/doc/html/rfc4210)
for issuing and renewing leaf certificates.

### CMPv2 Protocol Paths <EnterpriseAlert inline="true" />

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


### Read CMPv2 Configuration <EnterpriseAlert inline="true" />

This endpoint fetches the current CMPv2 configuration.

| Method | Path              |
| :----- |:------------------|
| `GET`  | `/pki/config/cmp` |

#### Sample request

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

#### Sample response

```json
{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "default_path_policy": "role:example-role",
    "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 <EnterpriseAlert inline="true" />

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

| Method | Path              |
|:-------|:------------------|
| `POST` | `/pki/config/cmp` |

#### 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](/vault/api-docs/auth/cert#name-6) 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`


#### Sample Payload

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

#### Sample request

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

#### Sample response

```json
{
  "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",
    "enabled": true,
    "enable_sentinel_parsing": true,
    "last_updated": "2024-02-02T10:49:20-05:00"
  }
}
```