1 files changed, 30 insertions, 0 deletions
diff --git a/docs/en/rst/integrating/auth-delegation.rst b/docs/en/rst/integrating/auth-delegation.rst
new file mode 100644
index 000000000..811da0d90
--- /dev/null
+++ b/docs/en/rst/integrating/auth-delegation.rst
@@ -0,0 +1,30 @@
+.. _auth-delegation:
+
+Authentication Delegation via API Keys
+######################################
+
+Bugzilla provides a mechanism for web apps to request (with the user's consent)
+an API key. API keys allow the web app to perform any action as the user and are as
+a result very powerful. Because of this power, this feature is disabled by default.
+
+Authentication Flow
+-------------------
+
+The authentication process begins by directing the user to th the Bugzilla site's auth.cgi.
+For the sake of this example, our application's URL is `http://app.example.org`
+and the Bugzilla site is `http://bugs.example.org`.
+
+1. Provide a link or redirect the user to `http://bugs.example.org/auth.cgi?callback=http://app.example.org/callback&description=app%description`
+2. Assuming the user is agreeable, they will be redirected to `http://app.example.org/callback` via a GET request
+   with two additional parameters: `client_api_key` and `client_api_login`.
+3. Finally, you should check that the API key and login are valid, using the :ref:`rest_user_valid_login` REST
+   resource.
+
+Your application should take measures to ensure when receiving a user at your
+callback URL that you previously redirected them to Bugzilla. The simplest method would be ensuring the callback url always has the
+hostname and path you specified, with only the query string parameters varying.
+
+The description should include the name of your application, in a form that will be recognizable to users.
+This description is used in the :ref:`API Keys tab <api-keys>` in the Preferences page.
+
+The API key passed to the callback will be valid until the user revokes it.