traefik/docs/content/operations/api.md

API

Traefik exposes a number of information through an API handler, such as the configuration of all routers, services, middlewares, etc.

As with all features of Traefik, this handler can be enabled with the static configuration.

Security

Enabling the API in production is not recommended, because it will expose all configuration elements, including sensitive data.

In production, it should be at least secured by authentication and authorizations.

A good sane default (non exhaustive) set of recommendations would be to apply the following protection mechanisms:

• At the application level:
  securing with middlewares such as basic authentication or white listing.

• At the transport level:
  NOT publicly exposing the API's port, keeping it restricted to internal networks (as in the principle of least privilege, applied to networks).

Configuration

To enable the API handler:

[api]

--api

dashboard

Optional, Default=true

Enable the dashboard. More about the dashboard features here.

[api]
  dashboard = true

--api.dashboard

entrypoint

Optional, Default="traefik"

The entry point that the API handler will be bound to. The default ("traefik") is an internal entry point (which is always defined).

[api]
  entrypoint = "web"

--api.entrypoint="web"

middlewares

Optional, Default=empty

The list of middlewares applied to the API handler.

[api]
  middlewares = ["api-auth", "api-prefix"]

--api.middlewares="api-auth,api-prefix"

debug

Optional, Default=false

Enable additional endpoints for debugging and profiling, served under /debug/.

[api]
  debug = true

--api.debug=true

Endpoints

All the following endpoints must be accessed with a GET HTTP request.

Path	Description
/api/http/routers	Lists all the HTTP routers information.
/api/http/routers/{name}	Returns the information of the HTTP router specified by name.
/api/http/services	Lists all the HTTP services information.
/api/http/services/{name}	Returns the information of the HTTP service specified by name.
/api/http/middlewares	Lists all the HTTP middlewares information.
/api/http/middlewares/{name}	Returns the information of the HTTP middleware specified by name.
/api/tcp/routers	Lists all the TCP routers information.
/api/tcp/routers/{name}	Returns the information of the TCP router specified by name.
/api/tcp/services	Lists all the TCP services information.
/api/tcp/services/{name}	Returns the information of the TCP service specified by name.
/api/version	Returns information about Traefik version.
/debug/vars	See the expvar Go documentation.
/debug/pprof/	See the pprof Index Go documentation.
/debug/pprof/cmdline	See the pprof Cmdline Go documentation.
/debug/pprof/profile	See the pprof Profile Go documentation.
/debug/pprof/symbol	See the pprof Symbol Go documentation.
/debug/pprof/trace	See the pprof Trace Go documentation.

Common Configuration Use Cases

Address / Port

You can define a custom address/port like this:

[entryPoints]
  [entryPoints.web]
  address = ":80"

  [entryPoints.foo]
  address = ":8082"

  [entryPoints.bar]
  address = ":8083"

[ping]
entryPoint = "foo"

[api]
entryPoint = "bar"

In the above example, you would access a service at /foo, an api endpoint, or the health-check as follows:

• Service: http://hostname:80/foo
• API: http://hostname:8083/api/http/routers
• Ping URL: http://hostname:8082/ping

Authentication

To restrict access to the API handler, one can add authentication with the basic auth middleware.

[api]
  middlewares=["api-auth"]

[http.middlewares]
  [http.middlewares.api-auth.basicauth]
  users = [
    "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
    "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
  ]