Blog HCP Consul on Azure goes GA, plus more Consul news from HashiConf EU Read more
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
  • API Introduction
    • Consistency Modes
    • Blocking Queries
    • Filtering
    • Agent Caching

    • Overview
    • Tokens
    • Legacy Tokens
    • Policies
    • Roles
    • Auth Methods
    • Binding Rules
  • Admin Partitions
    • Overview
    • Checks
    • Services
    • Connect
  • Catalog
  • Cluster Peering
  • Config
    • Overview
    • Certificate Authority (CA)
    • Intentions
  • Coordinates
  • Discovery Chain
  • Events
  • Health
  • KV Store
    • Overview
    • Area
    • Autopilot
    • Keyring
    • License
    • Raft
    • Segment
  • Namespaces
  • Prepared Queries
  • Sessions
  • Snapshots
  • Status
  • Transactions

  • Libraries & SDKs
Type '/' to Search

»Session HTTP Endpoint

The /session endpoints create, destroy, and query sessions in Consul.

»Create Session

This endpoint initializes a new session. Sessions must be associated with a node and may be associated with any number of checks.

MethodPathProduces
PUT/session/createapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonesession:write

»Query Parameters

  • ns (string: "")

    Enterprise
    - Specifies the namespace to query. You can also specify the namespace through other methods.

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter. Using this parameter across datacenters is not recommended.

»JSON Request Body Schema

  • LockDelay (string: "15s") - Specifies the duration for the lock delay. This must be greater than 0.

  • Node (string: "<agent>") - Specifies the name of the node. This field must refer to a node that is already registered.

  • Name (string: "") - Specifies a human-readable name for the session.

  • Checks (array<string>: nil) - Specifies a list of node health check IDs (commonly CheckID in API responses). It is highly recommended that, if you override this list, you include the default serfHealth. Deprecated in Consul 1.7.0 and replaced by NodeChecks. This field will be omitted from the API response in Consul 1.7+ if serfHealth is the only defined check.

  • NodeChecks (array<string>: nil) - Specifies a list of node health check IDs (commonly CheckID in API responses). It is highly recommended that, if you override this list, you include the default serfHealth. Added in Consul 1.7.0.

  • ServiceChecks (array<ServiceCheck>: nil) - Specifies a list of service checks. Added in Consul 1.7.0. A service check has the following fields:

    • ID (string: <required>) - The ID of the service check to monitor (commonly CheckID in API responses).

    • Namespace (string: "")

      Enterprise
      - Specifies the namespace in which to resolve the service check ID.

  • Behavior (string: "release") - Controls the behavior to take when a session is invalidated. Valid values are:

    • release - causes any locks that are held to be released
    • delete - causes any locks that are held to be deleted
  • TTL (string: "") - Specifies the duration of a session (between 10s and 86400s). If provided, the session is invalidated if it is not renewed before the TTL expires. The lowest practical TTL should be used to keep the number of managed sessions low. When locks are forcibly expired, such as when following the leader election pattern in an application, sessions may not be reaped for up to double this TTL, so long TTL values (> 1 hour) should be avoided. Valid time units include "s", "m" and "h".

»Sample Payload

{
  "LockDelay": "15s",
  "Name": "my-service-lock",
  "Node": "foobar",
  "Checks": ["a", "b", "c"],
  "Behavior": "release",
  "TTL": "30s"
}
{
  "LockDelay": "15s",
  "Name": "my-service-lock",
  "Node": "foobar",
  "Checks": ["a", "b", "c"],
  "Behavior": "release",
  "TTL": "30s"
}

»Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/session/create
$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/session/create

»Sample Response

{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
  • ID - the ID of the created session

»Delete Session

This endpoint destroys the session with the given name. If the session UUID is malformed, an error is returned. If the session UUID does not exist or already expired, a 200 is still returned (the operation is idempotent).

MethodPathProduces
PUT/session/destroy/:uuidapplication/json

Even though the Content-Type is application/json, the response is either a literal true or false, indicating of whether the destroy was successful.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonesession:write

»Path Parameters

  • uuid (string: <required>) - Specifies the UUID of the session to destroy. This is required and is specified as part of the URL path.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. Using this parameter across datacenters is not recommended.

  • ns (string: "")

    Enterprise
    - Specifies the namespace to query. You can also specify the namespace through other methods.

»Sample Request

$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/session/destroy/adf4238a-882b-9ddc-4a9d-5b6758e4159e
$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/session/destroy/adf4238a-882b-9ddc-4a9d-5b6758e4159e

»Sample Response

true
true

»Read Session

This endpoint returns the requested session information.

MethodPathProduces
GET/session/info/:uuidapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonesession:read

»Path Parameters

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

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This defaults to the datacenter of the agent being queried. Using this parameter across datacenters is not recommended.

  • ns (string: "")

    Enterprise
    - Specifies the namespace to query. You can also specify the namespace through other methods.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/session/info/adf4238a-882b-9ddc-4a9d-5b6758e4159e
$ curl \
    http://127.0.0.1:8500/v1/session/info/adf4238a-882b-9ddc-4a9d-5b6758e4159e

»Sample Response

[
  {
    "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    "Name": "test-session",
    "Node": "raja-laptop-02",
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": "30s",
    "NodeChecks": [
      "serfHealth"
    ],
    "ServiceChecks": null,
    "CreateIndex": 1086449,
    "ModifyIndex": 1086449
  }
]
[
  {
    "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    "Name": "test-session",
    "Node": "raja-laptop-02",
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": "30s",
    "NodeChecks": [
      "serfHealth"
    ],
    "ServiceChecks": null,
    "CreateIndex": 1086449,
    "ModifyIndex": 1086449
  }
]

If the session does not exist, an empty JSON list [] is returned.

»List Sessions for Node

This endpoint returns the active sessions for a given node.

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.

MethodPathProduces
GET/session/node/:nodeapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonesession:read

»Path Parameters

  • node (string: <required>) - Specifies the name or ID of the node to query.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. Using this parameter across datacenters is not recommended.

  • ns (string: "")

    Enterprise
    - Specifies the namespace to query. You can also specify the namespace through other methods.

    The namespace may be specified as '*' and then results will be returned for all namespaces.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/session/node/node-abcd1234
$ curl \
    http://127.0.0.1:8500/v1/session/node/node-abcd1234

»Sample Response

[
  {
    "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    "Name": "test-session",
    "Node": "node-abcd1234",
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": "30s",
    "NodeChecks": [
      "serfHealth"
    ],
    "ServiceChecks": null,
    "CreateIndex": 1086449,
    "ModifyIndex": 1086449
  }
]
[
  {
    "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    "Name": "test-session",
    "Node": "node-abcd1234",
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": "30s",
    "NodeChecks": [
      "serfHealth"
    ],
    "ServiceChecks": null,
    "CreateIndex": 1086449,
    "ModifyIndex": 1086449
  }
]

»List Sessions

This endpoint returns the list of active sessions.

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.

MethodPathProduces
GET/session/listapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonesession:read

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. Using this parameter across datacenters is not recommended.

  • ns (string: "")

    Enterprise
    - Specifies the namespace to query. You can also specify the namespace through other methods.

    The namespace may be specified as '*' and then results will be returned for all namespaces.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/session/list
$ curl \
    http://127.0.0.1:8500/v1/session/list

»Sample Response

[
  {
    "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    "Name": "test-session",
    "Node": "raja-laptop-02",
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": "30s",
    "NodeChecks": [
      "serfHealth"
    ],
    "ServiceChecks": null,
    "CreateIndex": 1086449,
    "ModifyIndex": 1086449
  }
]
[
  {
    "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    "Name": "test-session",
    "Node": "raja-laptop-02",
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": "30s",
    "NodeChecks": [
      "serfHealth"
    ],
    "ServiceChecks": null,
    "CreateIndex": 1086449,
    "ModifyIndex": 1086449
  }
]

»Renew Session

This endpoint renews the given session. This is used with sessions that have a TTL, and it extends the expiration by the TTL.

MethodPathProduces
PUT/session/renew/:uuidapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonesession:write

»Path Parameters

  • uuid (string: <required>) - Specifies the UUID of the session to renew.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. Using this parameter across datacenters is not recommended.

  • ns (string: "")

    Enterprise
    - Specifies the namespace to query. You can also specify the namespace through other methods.

»Sample Request

$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/session/renew/adf4238a-882b-9ddc-4a9d-5b6758e4159e
$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/session/renew/adf4238a-882b-9ddc-4a9d-5b6758e4159e

»Sample Response

[
  {
    "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    "Name": "test-session",
    "Node": "raja-laptop-02",
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": "30s",
    "NodeChecks": [
      "serfHealth"
    ],
    "ServiceChecks": null,
    "CreateIndex": 1086449,
    "ModifyIndex": 1086449
  }
]
[
  {
    "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    "Name": "test-session",
    "Node": "raja-laptop-02",
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": "30s",
    "NodeChecks": [
      "serfHealth"
    ],
    "ServiceChecks": null,
    "CreateIndex": 1086449,
    "ModifyIndex": 1086449
  }
]

Note: Consul may return a TTL value higher than the one specified during session creation. This indicates the server is under high load and is requesting clients renew less often.

»Methods to Specify Namespace
Enterprise

Session endpoints support several methods for specifying the namespace of session resources with the following order of precedence:

  1. ns query parameter
  2. X-Consul-Namespace request header
  3. Namespace is inherited from the namespace of the request's ACL token (if any)
  4. The default namespace
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager