HTTP API Structure

The main interface to Consul is a RESTful HTTP API. The API can perform basic CRUD operations on nodes, services, checks, configuration, and more.

Authentication

When authentication is enabled, a Consul token should be provided to API requests using the X-Consul-Token header or with the Bearer scheme in the authorization header. This reduces the probability of the token accidentally getting logged or exposed. When using authentication, clients should communicate via TLS.

If no token is provided for an HTTP request then Consul will use the default ACL token if it has been configured. If no default ACL token was configured then the anonymous token will be used.

Below is an example using curl with X-Consul-Token.

  1. $ curl \
  2.     --header "X-Consul-Token: <consul token>" \
  3.     http://127.0.0.1:8500/v1/agent/members
  1. $ curl \
  2.     --header "X-Consul-Token: <consul token>" \
  3.     http://127.0.0.1:8500/v1/agent/members

Below is an example using curl with a RFC6750 Bearer token.

  1. $ curl \
  2.     --header "Authorization: Bearer <consul token>" \
  3.     http://127.0.0.1:8500/v1/agent/members
  1. $ curl \
  2.     --header "Authorization: Bearer <consul token>" \
  3.     http://127.0.0.1:8500/v1/agent/members

Previously this was provided via a ?token= query parameter. This functionality exists on many endpoints for backwards compatibility, but its use is highly discouraged, since it can show up in access logs as part of the URL.

To learn more about the ACL system read the documentation.

Version Prefix

All API routes are prefixed with /v1/. This documentation is only for the v1 API.

Formatted JSON Output

By default, the output of all HTTP API requests is minimized JSON. If the client passes pretty on the query string, formatted JSON will be returned.

HTTP Methods

Consul’s API aims to be RESTful, although there are some exceptions. The API responds to the standard HTTP verbs GET, PUT, and DELETE. Each API method will clearly document the verb(s) it responds to and the generated response. The same path with different verbs may trigger different behavior. For example:

  1. PUT /v1/kv/foo
  2. GET /v1/kv/foo
  1. PUT /v1/kv/foo
  2. GET /v1/kv/foo

Even though these share a path, the PUT operation creates a new key whereas the GET operation reads an existing key.

Here is the same example using curl:

  1. $ curl \
  2.     --request PUT \
  3.     --data 'hello consul' \
  4.     http://127.0.0.1:8500/v1/kv/foo
  1. $ curl \
  2.     --request PUT \
  3.     --data 'hello consul' \
  4.     http://127.0.0.1:8500/v1/kv/foo

URL-Encoded Resource Names

Some Consul HTTP API endpoints accept resource names in URL path or query parameters. To pass a resource name containing URL-invalid characters, such as / or , URL-encode the resource name into the URL.

However, we generally recommend using resource names that don’t require URL-encoding. Depending on the validation that Consul applies to a resource name, Consul may still reject a request if it considers the resource name invalid for that endpoint. And even if Consul considers the resource name valid, it may degrade other functionality, such as failed DNS lookups for nodes or services with names containing invalid DNS characters.

This HTTP API capability also allows the CLI to accept arguments with URL-invalid characters.

Invalid Characters

The linefeed character (%0a) will cause a request to be rejected even if it is URL-encoded.

Translated Addresses

Consul 0.7 added the ability to translate addresses in HTTP response based on the configuration setting for translate_wan_addrs. In order to allow clients to know if address translation is in effect, the X-Consul-Translate-Addresses header will be added if translation is enabled, and will have a value of true. If translation is not enabled then this header will not be present.

Default ACL Policy

All API responses for Consul versions after 1.9 will include an HTTP response header X-Consul-Default-ACL-Policy set to either “allow” or “deny” which mirrors the current value of the agent’s acl.default_policy option.

This is also the default intention enforcement action if no intention matches.

This is returned even if ACLs are disabled.

Results Filtered by ACLs

As of Consul 1.11, most list endpoints support an X-Consul-Results-Filtered-By-ACLs HTTP response header. This indicates that the response contains a partial subset of results, because some have been filtered out by ACL policies.

In order to limit information leakage, this header is only present for requests authenticated by a valid ACL token.

The following example uses curl to view the X-Consul-Results-Filtered-By-ACLs response header.

  1. $ curl \
  2.     --header "X-Consul-Token: <non-anonymous consul token>" \
  3.     --include \
  4.     http://127.0.0.1:8500/v1/catalog/services
  6. HTTP/1.1 200 OK
  7. Content-Type: application/json
  8. ...
  9. X-Consul-Default-Acl-Policy: deny
  10. X-Consul-Results-Filtered-By-Acls: true
  12. {
  13.   "redis": [],
  14.   "postgresql": ["primary", "secondary"]
  15. }
  1. $ curl \
  2.     --header "X-Consul-Token: <non-anonymous consul token>" \
  3.     --include \
  4.     http://127.0.0.1:8500/v1/catalog/services
  6. HTTP/1.1 200 OK
  7. Content-Type: application/json
  8. ...
  9. X-Consul-Default-Acl-Policy: deny
  10. X-Consul-Results-Filtered-By-Acls: true
  12. {
  13.   "redis": [],
  14.   "postgresql": ["primary", "secondary"]
  15. }

UUID Format

UUID-format identifiers generated by the Consul API use the hashicorp/go-uuid library.

These UUID-format strings are generated using high quality, purely random bytes. It is not intended to be RFC compliant, merely to use a well-understood string representation of a 128-bit value.