# HG changeset patch
# User Søren Løvborg <sorenl@unity3d.com>
# Date 2017-03-15 22:07:53
# Node ID 9059da57b431417d50703398e1653d3aa7008065
# Parent  62ac1470b748d919bf53076c378d7740d54b36ed

auth: improve API key documentation for users

Add a warning about API key implications on the actual My Accounts/
API keys page where users are likely to see it.

No warning is added to the admin page equivalent, under the assumptions
that admins can be trusted to either know what API keys are (or at least
not mess around with them when editing other users), and thus don't need
the admonishment.

diff --git a/docs/api/api.rst b/docs/api/api.rst
--- a/docs/api/api.rst
+++ b/docs/api/api.rst
@@ -9,6 +9,14 @@ methods. Everything is available by send
 ``<your_server>/_admin/api``.
 
 
+API keys
+--------
+
+Every Kallithea user automatically receives an API key, which they can
+view under "My Account". On this page, API keys can also be revoked, and
+additional API keys can be generated.
+
+
 API access
 ----------
 
diff --git a/kallithea/templates/admin/my_account/my_account_api_keys.html b/kallithea/templates/admin/my_account/my_account_api_keys.html
--- a/kallithea/templates/admin/my_account/my_account_api_keys.html
+++ b/kallithea/templates/admin/my_account/my_account_api_keys.html
@@ -79,6 +79,19 @@
     ${h.end_form()}
 </div>
 
+<div class="alert alert-warning">
+<p>${_('''
+API keys are used to let scripts or services access %s using your
+account, as if you had provided the script or service with your actual
+password.
+''') % (c.site_name or 'Kallithea')}</p>
+<p>${_('''
+Like passwords, API keys should therefore never be shared with others,
+nor passed to untrusted scripts or services. If such sharing should
+happen anyway, reset the API key on this page to prevent further use.
+''')}</p>
+</div>
+
 <script>
     $(document).ready(function(){
         $("#lifetime").select2({