Merge branch 'master' into 431-customerrors431-customerrors

3 files changed, 32 insertions, 1 deletions

diff --git a/docs/feature_matrix.rst b/docs/feature_matrix.rst
index 0f9021d..59f3f3a 100644
--- a/docs/feature_matrix.rst
+++ b/docs/feature_matrix.rst
@@ -17,6 +17,7 @@ OAuth 2 client and provider support for
 - Bearer Tokens
 - Draft MAC tokens
 - Token Revocation
+- Token Introspection
 - OpenID Connect Authentication
 
 with support for SAML2 and JWT tokens, dynamic client registration and more to
diff --git a/docs/oauth2/endpoints/endpoints.rst b/docs/oauth2/endpoints/endpoints.rst
index 5b3ecec..98599e8 100644
--- a/docs/oauth2/endpoints/endpoints.rst
+++ b/docs/oauth2/endpoints/endpoints.rst
@@ -14,11 +14,12 @@ client attempts to access the user resources on their behalf.
     :maxdepth: 2
 
     authorization
+    introspect
     token
     resource
     revocation
 
-There are three different endpoints, the authorization endpoint which mainly
+There are three main endpoints, the authorization endpoint which mainly
 handles user authorization, the token endpoint which provides tokens and the
 resource endpoint which provides access to protected resources. It is to the
 endpoints you will feed requests and get back an almost complete response. This
@@ -27,3 +28,6 @@ later (but it's applicable to all other web frameworks libraries).
 
 The main purpose of the endpoint in OAuthLib is to figure out which grant type
 or token to dispatch the request to.
+
+Then, you can extend your OAuth implementation by proposing introspect or
+revocation endpoints.
diff --git a/docs/oauth2/endpoints/introspect.rst b/docs/oauth2/endpoints/introspect.rst
new file mode 100644
index 0000000..53ade8b
--- /dev/null
+++ b/docs/oauth2/endpoints/introspect.rst
@@ -0,0 +1,26 @@
+===================
+Token introspection
+===================
+
+Introspect endpoints read opaque access and/or refresh tokens upon client
+request. Also known as tokeninfo.
+
+.. code-block:: python
+
+    # Initial setup
+    from your_validator import your_validator
+    server = WebApplicationServer(your_validator)
+
+    # Token revocation
+    uri = 'https://example.com/introspect'
+    headers, body, http_method = {}, 'token=sldafh309sdf', 'POST'
+
+    headers, body, status = server.create_introspect_response(uri,
+        headers=headers, body=body, http_method=http_method)
+
+    from your_framework import http_response
+    http_response(body, status=status, headers=headers)
+
+
+.. autoclass:: oauthlib.oauth2.IntrospectEndpoint
+    :members: