Add latest changes from gitlab-org/gitlab@master

1 files changed, 32 insertions, 1 deletions

diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
index 9030feb13a7..c70ca1a74d5 100644
--- a/doc/api/oauth2.md
+++ b/doc/api/oauth2.md
@@ -102,7 +102,7 @@ CAUTION: **Important:**
 Avoid using this flow for applications that store data outside of the GitLab
 instance. If you do, make sure to verify `application id` associated with the
 access token before granting access to the data
-(see [`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo)).
+(see [`/oauth/token/info`](#retrieving-the-token-info)).
 
 Unlike the web flow, the client receives an `access token` immediately as a
 result of the authorization request. The flow does not use the client secret
@@ -212,3 +212,34 @@ or you can put the token to the Authorization header:
 ```
 curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/user
 ```
+
+## Retrieving the Token Info
+
+To verify the details of a token you can call the `token/info` endpoint. This is provided from the doorkeeper gem (see [`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo)).
+
+You will need to supply the access token, either as a parameter
+
+```
+GET https://gitlab.example.com/oauth/token/info?access_token=OAUTH-TOKEN
+```
+
+Or in the Authorization header:
+
+```
+curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/oauth/token/info
+```
+
+You will receive the following in response:
+
+```json
+{
+    "resource_owner_id": 1,
+    "scope": ["api"],
+    "expires_in": null,
+    "application": {"uid": "1cb242f495280beb4291e64bee2a17f330902e499882fe8e1e2aa875519cab33"},
+    "created_at": 1575890427
+}
+```
+
+CAUTION: **Deprecated fields:**
+The fields `scopes` and `expires_in_seconds` are also included in the response. They are aliases for `scope` and `expires_in` respectively and have been included to prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions#from-4x-to-5x). Please don't rely on these fields as they will be removed in a later release.