Certificate Authority (CA) - Connect HTTP API
The /connect/ca
endpoints provide tools for interacting with Connect's
Certificate Authority mechanism.
List CA Root Certificates
This endpoint returns the current list of trusted CA root certificates in the cluster.
Method | Path | Produces |
---|---|---|
GET | /connect/ca/roots | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
YES | all | none | none |
Query Parameters
pem
(boolean: false)
- Specifies that the return body should be a PEM encoded certificate chain suitable for use by applications needing to trust Connect CA signed certificates. The Content-Type will be set toapplication/pem-certificate-chain
to indicate the format of the response.
Sample Request
Sample Response
Sample PEM Encoded Response
Get CA Configuration
This endpoint returns the current CA configuration.
Method | Path | Produces |
---|---|---|
GET | /connect/ca/configuration | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
YES | all | none | operator:write 1 |
operator:read
prior to versions 1.8.6, 1.7.10, and 1.6.10.The corresponding CLI command is consul connect ca get-config
.
Sample Request
Sample Response
Update CA Configuration
This endpoint updates the configuration for the CA. If this results in a new root certificate being used, the Root Rotation process will be triggered.
Method | Path | Produces |
---|---|---|
PUT | /connect/ca/configuration | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
NO | none | none | operator:write |
The corresponding CLI command is consul connect ca set-config
.
If currently using Vault CA provider:
If you intend to change the CA provider from Vault to another,
or to change the Vault provider's RootPKIPath
,
you must temporarily elevate the privileges of the Vault token
or auth method in use as described in the
Vault CA provider documentation.
JSON Request Body Schema
Provider
(string: <required>)
- Specifies the CA provider type to use.Config
(map[string]string: <required>)
- The raw configuration to use for the chosen provider. For more information on configuring the Connect CA providers, see Provider Config.ForceWithoutCrossSigning
(bool: false)
- Indicates that the CA change should be forced to complete even if the current CA doesn't support root cross-signing.Caution: Setting this field to
true
will cause temporary connection failures until service mesh proxies and/or Consul client agents receive a new certificate that establishes trust with the new root. Do not use this field unless you are sure you need it. Refer to Forced Rotation Without Cross-Signing for more detail.
Sample Payload
Sample Request