Skip to content

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.

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretParam: mysecret
- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"
"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam": "mysecret"
}
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretParam: mysecret
[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
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue": "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
}
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
[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.

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      kind: queryparam
- "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"
"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.kind": "queryparam"
}
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          kind: queryparam
[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    kind = "queryparam"

Advanced Configuration Example

Below is an advanced configuration example:

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"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretParam: mysecretheader
      secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
      kind: header
- "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"
"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",
}
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"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretParam: mysecretheader
          secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
          kind: header
[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretParam = "mysecretheader"
    secretValue = "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
    kind = "header"