Intentions - Connect HTTP API

The /connect/intentions endpoint provide tools for managing intentions.

1.9.0 and later: Reading and writing intentions has been migrated to the service-intentions config entry kind.

Upsert Intention by Name

1.9.0+: This API is available in Consul versions 1.9.0 and later.

This endpoint creates a new intention and returns true if it was created successfully.

The name and destination pair must be unique. If another intention matches the name and destination, the creation will replace the previous intention.

The intentions created by this endpoint will not be assigned the following fields: ID, CreatedAt, UpdatedAt. Additionally, the Meta field cannot be persisted using this endpoint and will require editing the enclosing service-intentions config entry for the destination.

Method	Path	Produces
`PUT`	`/connect/intentions/exact`	`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`	`intentions:write` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention create -replace.

Query Parameters

source (string: <required>) - Specifies the source service according to the source naming conventions.
destination (string: <required>) - Specifies the destination service according to the destination naming conventions.
ns (string: "") Enterprise - Specifies the default namespace to use when source or destination query parameters do not include a namespace as shown in the source and destination naming conventions. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

JSON Request Body Schema

SourceType (string: "") - The type for the SourceName value. This can be only "consul" today to represent a Consul service. If not provided, this will be defaulted to "consul".
Action (string: "") - For an L4 intention this is required, and should be set to one of "allow" or "deny" for the action that should be taken if this intention matches a request.
This should be omitted for an L7 intention as it is mutually exclusive with the Permissions field.
Permissions (array<IntentionPermission>) - The list of all additional L7 attributes that extend the intention match criteria.
Permission precedence is applied top to bottom. For any given request the first permission to match in the list is terminal and stops further evaluation. As with L4 intentions, traffic that fails to match any of the provided permissions in this intention will be subject to the default intention behavior is defined by the default ACL policy.
This should be omitted for an L4 intention as it is mutually exclusive with the Action field.
Description (string: "") - Description for the intention. This is not used by Consul, but is presented in API responses to assist tooling.

Sample Payload

{
  "SourceType": "consul",
  "Action": "allow"
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    "http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db"

Sample Response

true

Create Intention with ID

Deprecated - This endpoint is deprecated in Consul 1.9.0 in favor of upserting by name or editing the service-intentions config entry for the destination.

This endpoint creates a new intention and returns its ID if it was created successfully.

The name and destination pair must be unique. If another intention matches the name and destination, the creation will fail. You must either update the existing intention or delete it prior to creating a new one.

Method	Path	Produces
`POST`	`/connect/intentions`	`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`	`intentions:write` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention create.

Query Parameters

ns (string: "") Enterprise - Specifies the default namespace to use when SourceNS or DestinationNS request body parameters do not include a namespace as shown in the source and destination naming conventions. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

JSON Request Body Schema

SourceName (string: <required>) - The source of the intention. For a SourceType of consul this is the name of a Consul service. The service does not need to be registered.
SourceNS (string: "") Enterprise - The namespace for the SourceName parameter.
DestinationName (string: <required>) - The destination of the intention. The intention destination is always a Consul service, unlike the source. The service does not need to be registered.
DestinationNS (string: "") Enterprise - The namespace for the DestinationName parameter.
SourceType (string: "") - The type for the SourceName value. This can be only "consul" today to represent a Consul service. If not provided, this will be defaulted to "consul".
Action (string: <required>) - This is one of "allow" or "deny" for the action that should be taken if this intention matches a request.
Description (string: "") - Description for the intention. This is not used by Consul, but is presented in API responses to assist tooling.
Meta (map<string|string>: nil) - Specifies arbitrary KV metadata pairs.

Sample Payload

{
  "SourceName": "web",
  "DestinationName": "db",
  "SourceType": "consul",
  "Action": "allow"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/connect/intentions

Sample Response

{
  "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}

Update Intention by ID

Deprecated - This endpoint is deprecated in Consul 1.9.0 in favor of upserting by name or editing the service-intentions config entry for the destination.

This endpoint updates an intention with the given values.

Method	Path	Produces
`PUT`	`/connect/intentions/:uuid`	`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`	`intentions:write` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

This endpoint supports the same parameters as the create an intention endpoint. Additional parameters unique to this endpoint include:

Path Parameters

uuid (string: <required>) - Specifies the UUID of the intention to update.

Sample Payload

{
  "SourceName": "web",
  "DestinationName": "other-db",
  "SourceType": "consul",
  "Action": "allow"
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c

Read Specific Intention by Name

This endpoint reads a specific intention by its unique source and destination.

Method	Path	Produces
`GET`	`/connect/intentions/exact`	`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`	`intentions:read` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention get.

Query Parameters

source (string: <required>) - Specifies the source service according to the source naming conventions.
destination (string: <required>) - Specifies the destination service according to the destination naming conventions.
ns (string: "") Enterprise - Specifies the default namespace to use when source or destination query parameters do not include a namespace as shown in the source and destination naming conventions. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db

Sample Response

{
  "Description": "",
  "SourceNS": "default",
  "SourceName": "web",
  "DestinationNS": "default",
  "DestinationName": "db",
  "SourceType": "consul",
  "Action": "allow",
  "Meta": {},
  "Precedence": 9,
  "CreateIndex": 11,
  "ModifyIndex": 11
}

Read Specific Intention by ID

Deprecated - This endpoint is deprecated in Consul 1.9.0 in favor of reading by name or by viewing the service-intentions config entry for the destination.

This endpoint reads a specific intention.

Method	Path	Produces
`GET`	`/connect/intentions/:uuid`	`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`	`intentions:read` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention get.

Path Parameters

uuid (string: <required>) - Specifies the UUID of the intention to read.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c

Sample Response

{
  "ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
  "Description": "",
  "SourceNS": "default",
  "SourceName": "web",
  "DestinationNS": "default",
  "DestinationName": "db",
  "SourceType": "consul",
  "Action": "allow",
  "Meta": {},
  "Precedence": 9,
  "CreatedAt": "2018-05-21T16:41:27.977155457Z",
  "UpdatedAt": "2018-05-21T16:41:27.977157724Z",
  "CreateIndex": 11,
  "ModifyIndex": 11
}

List Intentions

This endpoint lists all intentions.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

Method	Path	Produces
`GET`	`/connect/intentions`	`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`	`intentions:read` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention list.

Query Parameters

filter (string: "") - Specifies the expression used to filter the queries results prior to returning the data.
ns (string: "") Enterprise - Specifies the namespace to list intentions from. The * wildcard may be used to list intentions from all namespaces. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl \
    'http://127.0.0.1:8500/v1/connect/intentions?filter=SourceName==web'

Sample Response

[
  {
    "Description": "",
    "SourceNS": "default",
    "SourceName": "web",
    "DestinationNS": "default",
    "DestinationName": "db",
    "SourceType": "consul",
    "Action": "allow",
    "Meta": {},
    "Precedence": 9,
    "CreateIndex": 11,
    "ModifyIndex": 11
  }
]

Filtering

The filter will be executed against each Intention in the result list with the following selectors and filter operations being supported:

Selector	Supported Operations
`Action`	Equal, Not Equal, In, Not In, Matches, Not Matches
`Description`	Equal, Not Equal, In, Not In, Matches, Not Matches
`DestinationNS`	Equal, Not Equal, In, Not In, Matches, Not Matches
`DestinationName`	Equal, Not Equal, In, Not In, Matches, Not Matches
`ID`	Equal, Not Equal, In, Not In, Matches, Not Matches
`Meta`	Is Empty, Is Not Empty, In, Not In
`Meta.<any>`	Equal, Not Equal, In, Not In, Matches, Not Matches
`Precedence`	Equal, Not Equal
`SourceNS`	Equal, Not Equal, In, Not In, Matches, Not Matches
`SourceName`	Equal, Not Equal, In, Not In, Matches, Not Matches
`SourceType`	Equal, Not Equal, In, Not In, Matches, Not Matches

Delete Intention by Name

1.9.0+: This API is available in Consul versions 1.9.0 and later.

This endpoint deletes a specific intention by its unique source and destination.

Method	Path	Produces
`DELETE`	`/connect/intentions/exact`	`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`	`intentions:write` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention delete.

Query Parameters

source (string: <required>) - Specifies the source service according to the source naming conventions.
destination (string: <required>) - Specifies the destination service according to the destination naming conventions.
ns (string: "") Enterprise - Specifies the default namespace to use when source or destination query parameters do not include a namespace as shown in the source and destination naming conventions. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl \
    --request DELETE \
    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db

Delete Intention by ID

Deprecated - This endpoint is deprecated in Consul 1.9.0 in favor of deleting by name or editing the service-intentions config entry for the destination.

This endpoint deletes a specific intention.

Method	Path	Produces
`DELETE`	`/connect/intentions/:uuid`	`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`	`intentions:write` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention delete.

Path Parameters

uuid (string: <required>) - Specifies the UUID of the intention to delete.

Sample Request

$ curl \
    --request DELETE \
    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c

Check Intention Result

This endpoint evaluates the intentions for a specific source and destination and returns whether the connection would be authorized or not given the current Consul configuration and set of intentions.

Note: This endpoint will always evaluate matching intentions with L7 Permissions defined as deny intentions because there is no request to check against.

For performance and reliability reasons it is desirable to implement intention enforcement by listing intentions that match the destination and representing them in the native configuration of the proxy itself (such as RBAC for Envoy).

This endpoint will work even if the destination service has intention = "deny" specifically set, because the resulting API response does not contain any information about the intention itself.

Method	Path	Produces
`GET`	`/connect/intentions/check`	`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`	`intentions:read` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention check.

Query Parameters

source (string: <required>) - Specifies the source service according to the source naming conventions.
destination (string: <required>) - Specifies the destination service according to the destination naming conventions.
ns (string: "") Enterprise - Specifies the default namespace to use when source or destination query parameters do not include a namespace as shown in the source and destination naming conventions. You can also specify the namespace through other methods.

Sample Request

$ curl \
    "http://127.0.0.1:8500/v1/connect/intentions/check?source=web&destination=db"

Sample Response

{
  "Allowed": true
}

Allowed is true if the connection would be allowed, false otherwise.

List Matching Intentions

This endpoint lists the intentions that match a given source or destination. The intentions in the response are in evaluation order.

Method	Path	Produces
`GET`	`/connect/intentions/match`	`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`	`background refresh`	`intentions:read` Define intention rules in the `service` policy. Refer to ACL requirements for intentions for additional information.

The corresponding CLI command is consul intention match.

Query Parameters

by (string: <required>) - Specifies whether to match the "name" value by "source" or "destination".
name (string: <required>) - Specifies a name to match according to the source and destination naming conventions. You can repeat this parameter for batching multiple matches.
ns (string: "") Enterprise - Specifies the default namespace to use when the name query parameter does not include a namespace as shown in the source and destination naming conventions. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl \
    "http://127.0.0.1:8500/v1/connect/intentions/match?by=source&name=web"

Sample Response

{
  "web": [
    {
      "Description": "",
      "SourceNS": "default",
      "SourceName": "web",
      "DestinationNS": "default",
      "DestinationName": "db",
      "SourceType": "consul",
      "Action": "deny",
      "Meta": {},
      "CreateIndex": 12,
      "ModifyIndex": 12
    },
    {
      "Description": "",
      "SourceNS": "default",
      "SourceName": "web",
      "DestinationNS": "default",
      "DestinationName": "*",
      "SourceType": "consul",
      "Action": "allow",
      "Meta": {},
      "CreateIndex": 11,
      "ModifyIndex": 11
    }
  ]
}

Methods to specify namespace Enterprise

Intention endpoints support several methods for specifying the namespace of intention resources with the following order of precedence:

ns query parameter
X-Consul-Namespace request header
Namespace is inherited from the namespace of the request's ACL token (if any)
The default namespace

Intentions - Connect HTTP API

Upsert Intention by Name

Query Parameters

JSON Request Body Schema

Sample Payload

Sample Request

Sample Response

Create Intention with ID

Query Parameters

JSON Request Body Schema

Sample Payload

Sample Request

Sample Response

Update Intention by ID

Path Parameters

Sample Payload

Sample Request

Read Specific Intention by Name

Query Parameters

Sample Request

Sample Response

Read Specific Intention by ID

Path Parameters

Sample Request

Sample Response

List Intentions

Query Parameters

Sample Request

Sample Response

Filtering

Delete Intention by Name

Query Parameters

Sample Request

Delete Intention by ID

Path Parameters

Sample Request

Check Intention Result

Query Parameters

Sample Request

Sample Response

List Matching Intentions

Query Parameters

Sample Request

Sample Response

Methods to specify namespace EnterpriseEnterprise

Methods to specify namespace Enterprise