apply codestyle and implementation changes to the respective feature codepersonal_access_token_api_and_impersonation_token

3 files changed, 44 insertions, 94 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index 759ec253a1f..c790e000945 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -8,7 +8,6 @@ under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api).
 Documentation for various API resources can be found separately in the
 following locations:
 
-- [Personal Access Tokens](personal_access_tokens.md)
 - [Award Emoji](award_emoji.md)
 - [Branches](branches.md)
 - [Broadcast Messages](broadcast_messages.md)
@@ -222,6 +221,14 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v3/projects"
 ```
 
+## Impersonation Tokens
+
+Impersonation Tokens are a type of Personal Access Token that can only be created by an admin for a specific user. These can be used by automated tools
+to authenticate with the API as a specific user, as a better alternative to using the user's password or private token directly, which may change over time,
+and to using the [Sudo](#sudo) feature, which requires the tool to know an admin's password or private token, which can change over time as well and are extremely powerful.
+
+For more information about the usage please refer to the [Users](users.md) page
+
 ## Pagination
 
 Sometimes the returned result will span across many pages. When listing
diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md
deleted file mode 100644
index ea156d92dc8..00000000000
--- a/doc/api/personal_access_tokens.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Personal Access Token
-
-## List
-
-This function takes pagination parameters `page` and `per_page` to restrict the list of personal access tokens.
-
-```
-GET /personal_access_tokens
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `state`   | string | no | filter tokens based on state (all, active, inactive) |
-
-Example response:
-```json
-[
-  {
-    "id": 1,
-    "name": "mytoken",
-    "revoked": false,
-    "expires_at": "2017-01-04",
-    "scopes": ["api"],
-    "active": true
-  }
-]
-```
-
-## Show
-
-```
-GET /personal_access_tokens/:personal_access_token_id
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `personal_access_token_id` | integer | yes | The ID of the personal access token |
-
-## Create
-
-```
-POST /personal_access_tokens
-```
-
-It responds with the new personal access token for the current user.
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `name` | string | yes | The name of the personal access token |
-| `expires_at` | date | no | The expiration date of the personal access token |
-| `scopes` | array | no | The array of scopes of the personal access token |
-
-## Revoke
-
-```
-DELETE /personal_access_tokens/:personal_access_token_id
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `personal_access_token_id` | integer | yes | The ID of the personal access token |
diff --git a/doc/api/users.md b/doc/api/users.md
index 91168c05dbe..4b7618d1019 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -828,22 +828,21 @@ Example response:
 ]
 ```
 
-## Retrieve user personal access tokens
+## Retrieve user impersonation tokens
 
-It retrieves every personal access token of the user. Note that only administrators can do this.
-This function takes pagination parameters `page` and `per_page` to restrict the list of personal access tokens.
+It retrieves every impersonation token of the user. Note that only administrators can do this.
+This function takes pagination parameters `page` and `per_page` to restrict the list of impersonation tokens.
 
 ```
-GET /users/:id/personal_access_tokens
+GET /users/:user_id/impersonation_tokens
 ```
 
 Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of the user |
+| `user_id` | integer | yes | The ID of the user |
 | `state`   | string | no | filter tokens based on state (all, active, inactive) |
-| `impersonation` | boolean | no | The impersonation flag of the personal access token |
 
 Example response:
 ```json
@@ -861,53 +860,66 @@ Example response:
 ]
 ```
 
-## Show a user personal access token
+## Show a user's impersonation token
 
-It shows a user's personal access token. Note that only administrators can do this.
+It shows a user's impersonation token. Note that only administrators can do this.
 
 ```
-GET /users/:id/personal_access_tokens/:personal_access_token_id
+GET /users/:user_id/impersonation_tokens/:impersonation_token_id
 ```
 
 Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of the user |
-| `personal_access_token_id` | integer | yes | The ID of the personal access token |
+| `user_id` | integer | yes | The ID of the user |
+| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
 
-## Create a personal access token
+## Create a impersonation token
 
-It creates a new personal access token. Note that only administrators can do this.
+It creates a new impersonation token. Note that only administrators can do this.
 You are only able to create impersonation tokens to impersonate the user and perform
 both API calls and Git reads and writes. The user will not see these tokens in his profile
 settings page.
 
 ```
-POST /users/:id/personal_access_tokens
+POST /users/:user_id/impersonation_tokens
 ```
 
 Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of the user |
-| `name` | string | yes | The name of the personal access token |
-| `expires_at` | date | no | The expiration date of the personal access token |
-| `scopes` | array | no | The array of scopes of the personal access token |
-| `impersonation` | boolean | no | The impersonation flag of the personal access token |
+| `user_id` | integer | yes | The ID of the user |
+| `name` | string | yes | The name of the impersonation token |
+| `expires_at` | date | no | The expiration date of the impersonation token |
+| `scopes` | array | no | The array of scopes of the impersonation token (api, read_user) |
 
-## Revoke a personal access token
+Example response:
+```json
+{
+  "id": 1,
+  "name": "mytoken",
+  "revoked": false,
+  "expires_at": "2017-01-04",
+  "scopes": ['api'],
+  "active": true,
+  "impersonation": true,
+  "token": "9koXpg98eAheJpvBs5tK"
+}
+```
 
-It revokes a personal access token. Note that only administrators can revoke impersonation tokens.
+## Revoke an impersonation token
+
+It revokes an impersonation token. Note that only administrators can revoke impersonation tokens.
 
 ```
-DELETE /users/:id/personal_access_tokens/:personal_access_token_id
+DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
 ```
 
 Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of the user |
-| `personal_access_token_id` | integer | yes | The ID of the personal access token |
+| `user_id` | integer | yes | The ID of the user |
+| `impersonation_token_id` | integer | yes | The ID of the impersonation token |