add doc for api key auth

Author: philkra

docs/security.asciidoc

@@ -24,6 +24,27 @@ $client = ClientBuilder::create()
 Credentials are provided per-host, which allows each host to have their own set of credentials.  All requests sent to the
 cluster will use the appropriate credentials depending on the node being talked to.
 
+=== ApiKey Authentication
+
+If your Elasticsearch cluster is secured by API keys as described https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html[here], you have two options to provide the values to the client.
+Either use the `id` and `api_key` pair from the create API key API response or use the encoded token as described https://www.elastic.co/guide/en/elasticsearch/reference/7.1/security-api-create-api-key.html#_examples_83[here] in the last code snippet.
+
+[source,php]
+----
+$client = ClientBuilder::create()
+                    ->setApiKeyPairAuthentication('id', 'api_key') <1>
+                    ->build();
+----
+<1> ApiKey pair of `id` and `api_key` from the create API key response.
+
+[source,php]
+----
+$client = ClientBuilder::create()
+                    ->setApiKeyAuthentication('encoded-api-key') <1>
+                    ->build();
+----
+<1> Encoded ApiKey pair
+
 === SSL Encryption
 
 Configuring SSL is a little more complex.  You need to identify if your certificate has been signed by a public