API Key Authentication

API Key Authentication Middleware

The API Key authentication middleware allows you to secure an API by requiring a base64-encoded secret key to be given, via HTTP header, cookie or query parameter.

Middleware Options

secretParam

Required, Default=""

The secretParam option should contain the name of the secret used by the middleware. For example, if the secret is passed via HTTP header, the value of secretParam should be the name of the header in which the secret is given.

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretParam: mysecret

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam": "mysecret"
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretParam: mysecret

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretParam = "mysecret"

secretValue

Required, Default=""

The secretValue option should contain a hash of the API key. Supported hashing algorithms are Bcrypt, SHA1 and MD5. The hash should be generated using htpasswd.

Generating hashes using htpasswd

htpasswd -nbB "" mypassword | cut -c 2- # hash "mypassword" using bcrypt
$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq

htpasswd -nbs "" mypassword | cut -c 2- # hash "mypassword" using sha1
{SHA}kd/Z3bQZiv/FwZTNjObTOP3kcOI=

htpasswd -nbm "" mypassword | cut -c 2- # hash "mypassword" using md5
$apr1$N9VxTJ9u$hwPGeJyzqvl1p1vwJo4HL1

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue": "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretValue = "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

kind

Optional, Default=""

The kind option can be given to explicitly declare how the secret should be given. Its values can be cookie, queryparam or header. If no value is specified for kind, the API key middleware looks for a secret in all 3 possible places, and if more than one is found, it considers the request to be bad.

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      kind: queryparam

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.kind": "queryparam"
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          kind: queryparam

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    kind = "queryparam"

Advanced Configuration Example

Below is an advanced configuration example:

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecretheader"
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=header"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretParam: mysecretheader
      secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
      kind: header

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecretheader"
- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
- "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=header"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam": "mysecretheader",
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue": "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG",
    "traefik.http.middlewares.test-apikey.plugin.apiKey.kind": "header",
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecretheader"
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=header"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretParam: mysecretheader
          secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
          kind: header

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretParam = "mysecretheader"
    secretValue = "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
    kind = "header"