Improve use cases documentation

Author: florimondmanca

README.md

@@ -29,10 +29,23 @@ API key permissions for the [Django REST Framework](https://www.django-rest-fram
 - 🔒 **As secure as possible**: API keys are treated with the same level of care than user passwords. They are hashed using the default password hasher before being stored in the database, and only visible at creation.
 - 🎨 **Customizable**: satisfy specific business requirements by building your own customized API key models, permission classes and admin panels. (Currently in public beta.)
 
-### Example use cases
+### Should I use API keys?
 
-- Using the built-in `APIKey` model, you can generate an API key and embed it in your frontend app server so that only it can access your API.
-- By customizing API key models and permissions, you can associate API keys to an entity (e.g. a user, person, organization…), and then build endpoints to allow them to manage their API keys.
+There are important security aspects you need to consider before switching to an API key access control scheme. We've listed some of these in [Security caveats](security.md#caveats), including serving your API over HTTPS.
+
+Besides, see [Why and when to use API keys](https://cloud.google.com/endpoints/docs/openapi/when-why-api-key#top_of_page) for hints on whether API keys can fit your use case.
+
+API keys are ideal in the following situations:
+
+- Blocking anonymous traffic.
+- Implementing API key-based [throttling](https://www.django-rest-framework.org/api-guide/throttling/). (Note that Django REST Framework already has may built-in utilities for this use case.)
+- Identifying usage patterns by logging request information along with the API key.
+
+They can also present enough security for authorizing internal services, such as your API server and an internal frontend application.
+
+> Please note that this package is NOT meant for authentication. You should NOT use this package  to identify individual users, either directly or indirectly.
+>
+> If you need server-to-server authentication, you may want to consider OAuth instead. Libraries such as [django-oauth-toolkit](https://django-oauth-toolkit.readthedocs.io/en/latest/index.html) can help.
 
 ## Quickstart
 

docs/guide.md

@@ -157,6 +157,9 @@ This package provides various customization APIs that allow you to extend its ba
 
 If the built-in `APIKey` model doesn't fit your needs, you can create your own by subclassing `AbstractAPIKey`. This is particularly useful if you need to **store extra information** or **link API keys to other models** using a `ForeignKey` or a `ManyToManyField`.
 
+!!! warning
+    Associating API keys to users, directly or indirectly, can present a security risk. See also: [Should I use API keys?](/#should-i-use-api-keys).
+ 
 #### Example
 
 Here's how you could link API keys to an imaginary `Organization` model:

docs/index.md

@@ -35,13 +35,24 @@
 - 🔒 **As secure as possible**: API keys are treated with the same level of care than user passwords. They are hashed using the default password hasher before being stored in the database, and only visible at creation.
 - 🎨 **Customizable**: satisfy specific business requirements by building your own customized API key models, permission classes and admin panels. (Currently in public beta.)
 
-!!! info
-    There are important security aspects you need to consider before switching to an API key access control scheme. See [Security caveats](security.md#caveats).
+### Should I use API keys?
 
-### Example use cases
+There are important security aspects you need to consider before switching to an API key access control scheme. We've listed some of these in [Security caveats](security.md#caveats), including serving your API over HTTPS.
 
-- Using the built-in `APIKey` model, you can generate an API key and embed it in your frontend app server so that only it can access your API.
-- By customizing API key models and permissions, you can associate API keys to an entity (e.g. a user, person, organization…), and then build endpoints to allow them to manage their API keys.
+Besides, see [Why and when to use API keys](https://cloud.google.com/endpoints/docs/openapi/when-why-api-key#top_of_page) for hints on whether API keys can fit your use case.
+
+API keys are ideal in the following situations:
+
+- Blocking anonymous traffic.
+- Implementing API key-based [throttling](https://www.django-rest-framework.org/api-guide/throttling/). (Note that Django REST Framework already has may built-in utilities for this use case.)
+- Identifying usage patterns by logging request information along with the API key.
+
+They can also present enough security for authorizing internal services, such as your API server and an internal frontend application.
+
+!!! warning
+    Please note that this package is NOT meant for authentication. You should NOT use this package  to identify individual users, either directly or indirectly.
+
+    If you need server-to-server authentication, you may want to consider OAuth instead. Libraries such as [django-oauth-toolkit](https://django-oauth-toolkit.readthedocs.io/en/latest/index.html) can help.
 
 ## Quickstart
 

docs/security.md

@@ -1,6 +1,8 @@
 # Security
 
-## Key generation scheme
+## Implementation details
+
+### Key generation scheme
 
 An API key is composed of two items:
 
@@ -14,7 +16,7 @@ The generated key that clients use to [make authorized requests](#making-authori
 
 [^1]: All hashers provided by Django should be supported. `djangorestframework-api-key` is tested against the [default list of `PASSWORD_HASHERS`](https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-PASSWORD_HASHERS). See also [How Django stores passwords](https://docs.djangoproject.com/en/2.2/topics/auth/passwords/#how-django-stores-passwords) for more information.
 
-## Grant scheme
+### Grant scheme
 
 Access is granted if and only if all of the following is true:
 
@@ -27,9 +29,11 @@ Access is granted if and only if all of the following is true:
 
 ## Caveats
 
-[API keys ≠ Security](https://nordicapis.com/why-api-keys-are-not-enough/): depending on your situation, you should probably not rely on API keys only to authenticate/authorize your clients.
+[API keys ≠ Security](https://nordicapis.com/why-api-keys-are-not-enough/): depending on your situation, you should probably not use API keys only to authorize your clients.
+
+Besides, you do NOT recommend using this package for authentication, i.e. retrieving user information from API keys.
 
-**Using API keys shifts the responsability of Information Security on your clients**. This induces risks, especially if detaining an API key gives access to confidential information or write operations. For example, an attacker could impersonate clients if they let their API keys leak.
+Inded, **using API keys shifts the responsability of Information Security on your clients**. This induces risks, especially if detaining an API key gives access to confidential information or write operations. For example, an attacker could impersonate clients if they let their API keys leak.
 
 As a best practice, you should apply the _Principle of Least Privilege_: allow only those who require resources to access those specific resources. In other words: **if your client needs to access an endpoint, add API permissions on that endpoint only** instead of the whole API.