added documentation, info to the readme, changelog and added myself to contributors

Author: Jens Timmerman

AUTHORS

@@ -17,3 +17,4 @@ Diego Garcia
 Bas van Oostveen
 Bart Merenda
 Paul Oswald
+Jens Timmerman

README.rst

@@ -100,6 +100,7 @@ Changelog
 Development
 ~~~~~~~~~~~
 
+* #396: added an IsAuthenticatedOrTokenHasScope Permission
 * #357: Support multiple-user clients by allowing User to be NULL for Applications
 
 0.10.0 [2015-12-14]

docs/changelog.rst

@@ -4,6 +4,7 @@ Changelog
 Development
 ~~~~~~~~~~~
 
+* #396: added an IsAuthenticatedOrTokenHasScope Permission
 * #357: Support multiple-user clients by allowing User to be NULL for Applications
 
 

docs/rest-framework/permissions.rst

@@ -63,3 +63,21 @@ When the request's method is one of "non safe" methods, the access is allowed on
         required_scopes = ['music']
 
 The `required_scopes` attribute is mandatory (you just need inform the resource scope).
+
+
+IsAuthenticatedOrTokenHasScope
+------------------------------
+The `TokenHasResourceScope` permission class allows the access only when the current access token has been authorized for **all** the scopes listed in the `required_scopes` field of the view but according of request's method.
+And also allows access to Authenticated users who are authenticated in django, but were not authenticated trought the OAuth2Authentication class.
+This allows for protection of the api using scopes, but still let's users browse the full browseable API.
+To restrict users to only browse the parts of the browseable API they should be allowed to see, you can combine this wwith the DjangoModelPermission or the DjangoObjectPermission.
+
+For example:
+
+.. code-block:: python
+
+    class SongView(views.APIView):
+        permission_classes = [IsAuthenticatedOrTokenHasScope, DjangoModelPermission]
+        required_scopes = ['music']
+
+The `required_scopes` attribute is mandatory.