open-consul/website/content/api-docs/connect/intentions.mdx

---
layout: api
page_title: Intentions - Connect - HTTP API
description: |-
  The /connect/intentions endpoint provide tools for managing intentions via
  Consul's HTTP API.
---

# Intentions - Connect HTTP API

The `/connect/intentions` endpoint provide tools for managing
[intentions](/docs/connect/intentions).

-> **1.9.0 and later:** Reading and writing intentions has been
migrated to the
[`service-intentions`](/docs/connect/config-entries/service-intentions)
config entry kind.

## Upsert Intention by Name ((#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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                   |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention create -replace`](/commands/intention/create#replace).

### Query Parameters

- `source` `(string: <required>)` - Specifies the source service
  according to the [source naming conventions](/commands/intention#source-and-destination-naming).

- `destination` `(string: <required>)` - Specifies the destination service
  according to the [destination naming conventions](/commands/intention#source-and-destination-naming).

- `ns` `(string: "")` <EnterpriseAlert inline /> - 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](/commands/intention#source-and-destination-naming).
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### 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](/docs/connect/config-entries/service-intentions#intentionpermission)
  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](/docs/agent/config/config-files#acl_default_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

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

### Sample Request

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

### Sample Response

```json
true
```

## Create Intention with ID

-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
[upserting by name](#upsert-intention-by-name) or editing the
[`service-intentions`](/docs/connect/config-entries/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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                   |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention create`](/commands/intention/create).

### Query Parameters

- `ns` `(string: "")` <EnterpriseAlert inline /> - 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](/commands/intention#source-and-destination-naming).
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### 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: "")` <EnterpriseAlert inline /> - 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: "")` <EnterpriseAlert inline /> - 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

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

### Sample Request

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

### Sample Response

```json
{
  "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](#upsert-intention-by-name) or editing the
[`service-intentions`](/docs/connect/config-entries/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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                   |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

This endpoint supports the same parameters as the [create an intention](#create-intention-with-id) endpoint.
Additional parameters unique to this endpoint include:

### Path Parameters

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

### Sample Payload

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

### Sample Request

```shell-session
$ 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 ((##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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                  |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES`            | `all`             | `none`        | `intentions:read`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention get`](/commands/intention/get).

### Query Parameters

- `source` `(string: <required>)` - Specifies the source service
  according to the [source naming conventions](/commands/intention#source-and-destination-naming).

- `destination` `(string: <required>)` - Specifies the destination service
  according to the [destination naming conventions](/commands/intention#source-and-destination-naming).

- `ns` `(string: "")` <EnterpriseAlert inline /> - 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](/commands/intention#source-and-destination-naming).
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### Sample Request

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

### Sample Response

```json
{
  "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](#read-specific-intention-by-name) or by viewing the
[`service-intentions`](/docs/connect/config-entries/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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                  |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES`            | `all`             | `none`        | `intentions:read`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention get`](/commands/intention/get).

### Path Parameters

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

### Sample Request

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

### Sample Response

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

@include 'http_api_results_filtered_by_acls.mdx'

| Method | Path                  | Produces           |
| ------ | --------------------- | ------------------ |
| `GET`  | `/connect/intentions` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                  |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `YES`            | `all`             | `none`        | `intentions:read`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention list`](/commands/intention/list).

### Query Parameters

- `filter` `(string: "")` - Specifies the expression used to filter the
  queries results prior to returning the data.

- `ns` `(string: "")` <EnterpriseAlert inline /> - 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](#methods-to-specify-namespace).

### Sample Request

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

### Sample Response

```json
[
  {
    "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 ((#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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                   |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention delete`](/commands/intention/delete).

### Query Parameters

- `source` `(string: <required>)` - Specifies the source service
  according to the [source naming conventions](/commands/intention#source-and-destination-naming).

- `destination` `(string: <required>)` - Specifies the destination service
  according to the [destination naming conventions](/commands/intention#source-and-destination-naming).

- `ns` `(string: "")` <EnterpriseAlert inline /> - 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](/commands/intention#source-and-destination-naming).
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### Sample Request

```shell-session
$ 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](#delete-intention-by-name) or editing the
[`service-intentions`](/docs/connect/config-entries/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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                   |
| ---------------- | ----------------- | ------------- | ------------------------------ |
| `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention delete`](/commands/intention/delete).

### Path Parameters

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

### Sample Request

```shell-session
$ 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 intentions with `Permissions`
defined as _deny_ intentions during. This endpoint is only suited for
networking layer 4 (e.g. TCP) integration.

For performance and reliability reasons it is desirable to implement intention
enforcement by listing [intentions that match the
destination](/api-docs/connect/intentions#list-matching-intentions) 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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                  |
| ---------------- | ----------------- | ------------- | ----------------------------- |
| `NO`             | `none`            | `none`        | `intentions:read`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention check`](/commands/intention/check).

### Query Parameters

- `source` `(string: <required>)` - Specifies the source service
  according to the [source naming conventions](/commands/intention#source-and-destination-naming).

- `destination` `(string: <required>)` - Specifies the destination service
  according to the [destination naming conventions](/commands/intention#source-and-destination-naming).

- `ns` `(string: "")` <EnterpriseAlert inline /> - 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](/commands/intention#source-and-destination-naming).
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### Sample Request

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

### Sample Response

```json
{
  "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](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching        | ACL Required                  |
| ---------------- | ----------------- | -------------------- | ----------------------------- |
| `YES`            | `all`             | `background refresh` | `intentions:read`<sup>1</sup> |

<p>
  <sup>1</sup> Intention ACL rules are specified as part of a{' '}
  <code>service</code> rule. See{' '}
  <a href="/docs/connect/intentions#intention-management-permissions">
    Intention Management Permissions
  </a>{' '}
  for more details.
</p>

The corresponding CLI command is [`consul intention match`](/commands/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](/commands/intention#source-and-destination-naming).
  You can repeat this parameter for batching multiple matches.

- `ns` `(string: "")` <EnterpriseAlert inline /> - 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](/commands/intention#source-and-destination-naming).
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### Sample Request

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

### Sample Response

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

Connect intention endpoints
support several methods for specifying the namespace of intention resources
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace