API Key Authentication

API-key-based authentication provides the simplest form of authentication or identification using single shared secrets. Each client request contains the API key as a request header or as a query parameter.

It is recommended to use API key authentication only with encrypted transport (HTTPS), as the API keys are provided with every client request and in plain text.

The secrets are stored on the server side in plain text. Please ensure that the configuration files have appropriate permissions.

Example configuration

The following configuration will allow the consumers foo and bar with API keys key1 and key2, access to example.com/ and paths below. Multiple consumers can be added.

{
    "name": "example",
    "host": "example.com",
    "path": "/*",
    "modules": [
        {
            "order": 0,
            "name": "auth-apikey",
            "consumers": {
                "foo": {
                    "secret": "key1"
                },
                "bar": {
                    "secret": "key2"
                }
            },
            "general": {
                    "optional": true
            }
        }
    ]
}

Consumer configuration attributes

Attribute	Required	Type	Description
`secret`	Yes	String	The key required to get access.

Default configuration attributes

Attribute	Required	Type	Default	Description
`optional`	No	Bool	False	The default value `false` will require `apikey` to be set for incoming requests to be authorized. If set to `true`, requests without apikey will be authorized but not authenticated while at the same time requests with apikey will also be authenticated.

Request headers

Header	Required	Type	Description
`apikey`	Yes	String	The key required to get access. If the `optional` attribute is set to `true`, requests without apikey will be authorized but not authenticated.

The apikey can also be specified as a query parameter.

Response status

Status	Description
`200`	The request was authorized to access the specified resource.
`401`	Unauthorized.

Response headers

Header	Description
`X-Auth-Error`	Any human readable authentication error, if present.
`X-Auth-Type`	The auth type used, will with this module be `apikey`.
`X-Auth-User`	The username of the authorized user.
`X-Auth-Id`	The username of the authorized user.