From 09dd6a7ead97122385f13265ea147ab689994244 Mon Sep 17 00:00:00 2001 From: Simon Vocella Date: Wed, 4 Jan 2017 11:51:17 +0100 Subject: add documentation and changelog entry for user personal access tokens api --- doc/api/README.md | 1 + doc/api/personal_access_tokens.md | 61 +++++++++++++++++++++++++++ doc/api/users.md | 86 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 148 insertions(+) create mode 100644 doc/api/personal_access_tokens.md (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 1c3b2ad0fbc..e40e2d81faf 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -8,6 +8,7 @@ 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: +- [Access Tokens](personal_access_tokens.md) - [Award Emoji](award_emoji.md) - [Branches](branches.md) - [Broadcast Messages](broadcast_messages.md) diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md new file mode 100644 index 00000000000..da666ccbc10 --- /dev/null +++ b/doc/api/personal_access_tokens.md @@ -0,0 +1,61 @@ +# Personal Access Token + +## List + +``` +GET /personal_access_tokens +``` + +An example: +```json +[ + { + "id": 1, + "name": "mytoken", + "revoked": false, + "expires_at": "2017-01-04", + "scopes": ['api'], + "active": true + } +] +``` + +In addition, you can filter users based on state: `all`, `active` and `inactive` + +``` +GET /personal_access_tokens?state=all +``` + +``` +GET /personal_access_tokens?state=active +``` + +``` +GET /personal_access_tokens?state=inactive +``` + +## Create + +``` +POST /personal_access_tokens +``` + +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 d14548e8bbb..f33090b132b 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -827,3 +827,89 @@ Example response: } ] ``` + +## Retrieve user personal access tokens + +It retrieves every personal access token of the user. Note that only administrators can do this. + +``` +GET /users/:user_id/personal_access_tokens +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `user_id` | integer | yes | The ID of the user | + +An example: +```json +[ + { + "id": 1, + "name": "mytoken", + "revoked": false, + "expires_at": "2017-01-04", + "scopes": ['api'], + "active": true, + "impersonation": false, + "token": "9koXpg98eAheJpvBs5tK" + } +] +``` + +In addition, you can filter users based on state: `all`, `active` and `inactive` + +``` +GET /users/:user_id/personal_access_tokens?state=all +``` + +``` +GET /users/:user_id/personal_access_tokens?state=active +``` + +``` +GET /users/:user_id/personal_access_tokens?state=inactive +``` + +Finally, you can filter based on impersonation: `true` or `false`. + +``` +GET /users/:user_id/personal_access_tokens?impersonation=true +``` + +## Create a personal access token + +It creates a new personal access token. Note that only administrators can do this. +If you set the impersonation flag to true, you can impersonate the user and +performing both API calls and Git reads and writes. The user will not see these +tokens in his profile settings. + +``` +POST /users/:user_id/personal_access_tokens +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `user_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 | + +## Revoke a personal access token + +It revokes a personal access token. Note that only administrators can revoke impersonation tokens. + +``` +DELETE /users/:user_id/personal_access_tokens/:personal_access_token_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `user_id` | integer | yes | The ID of the user | +| `personal_access_token_id` | integer | yes | The ID of the personal access token | -- cgit v1.2.1 From f0ea7130f7bf0e7a3702d863b4d246f524b6c14a Mon Sep 17 00:00:00 2001 From: Tiago Botelho Date: Thu, 9 Feb 2017 15:21:09 +0000 Subject: refactors documentation and personal access tokens form to not allow admins to generate non impersionation tokens --- doc/api/README.md | 2 +- doc/api/personal_access_tokens.md | 16 ++++++++++++++-- doc/api/users.md | 23 +++++++++++++++++++---- 3 files changed, 34 insertions(+), 7 deletions(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index e40e2d81faf..759ec253a1f 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -8,7 +8,7 @@ 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: -- [Access Tokens](personal_access_tokens.md) +- [Personal Access Tokens](personal_access_tokens.md) - [Award Emoji](award_emoji.md) - [Branches](branches.md) - [Broadcast Messages](broadcast_messages.md) diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index da666ccbc10..0fd04a0033d 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -14,13 +14,13 @@ An example: "name": "mytoken", "revoked": false, "expires_at": "2017-01-04", - "scopes": ['api'], + "scopes": ["api"], "active": true } ] ``` -In addition, you can filter users based on state: `all`, `active` and `inactive` +In addition, you can filter tokens based on state: `all`, `active` and `inactive` ``` GET /personal_access_tokens?state=all @@ -34,6 +34,18 @@ GET /personal_access_tokens?state=active GET /personal_access_tokens?state=inactive ``` +## 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 ``` diff --git a/doc/api/users.md b/doc/api/users.md index f33090b132b..2b4099227bc 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -858,7 +858,7 @@ An example: ] ``` -In addition, you can filter users based on state: `all`, `active` and `inactive` +In addition, you can filter tokens based on state: `all`, `active` and `inactive` ``` GET /users/:user_id/personal_access_tokens?state=all @@ -878,12 +878,27 @@ Finally, you can filter based on impersonation: `true` or `false`. GET /users/:user_id/personal_access_tokens?impersonation=true ``` +## Show a user personal access token + +It shows a user's personal access token. Note that only administrators can do this. + +``` +GET /users/:user_id/personal_access_tokens/:personal_access_token_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `user_id` | integer | yes | The ID of the user | +| `personal_access_token_id` | integer | yes | The ID of the personal access token | + ## Create a personal access token It creates a new personal access token. Note that only administrators can do this. -If you set the impersonation flag to true, you can impersonate the user and -performing both API calls and Git reads and writes. The user will not see these -tokens in his profile settings. +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/:user_id/personal_access_tokens -- cgit v1.2.1 From 9f2e4742e354f5548b4956060f1bfa5ee3bd6657 Mon Sep 17 00:00:00 2001 From: Tiago Botelho Date: Thu, 23 Feb 2017 17:47:06 +0000 Subject: applies relevant changes to the code and code structure --- doc/api/personal_access_tokens.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc/api') diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 0fd04a0033d..81e6f10f0c6 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -52,6 +52,8 @@ Parameters: POST /personal_access_tokens ``` +It responds with the new personal access token for the current user. + Parameters: | Attribute | Type | Required | Description | -- cgit v1.2.1 From 2b474dc2b226460782413e634792cf83e791173b Mon Sep 17 00:00:00 2001 From: Tiago Botelho Date: Mon, 27 Feb 2017 18:56:54 +0000 Subject: refactors finder and correlated code --- doc/api/personal_access_tokens.md | 24 ++++++++-------------- doc/api/users.md | 43 ++++++++++++--------------------------- 2 files changed, 22 insertions(+), 45 deletions(-) (limited to 'doc/api') diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 81e6f10f0c6..ea156d92dc8 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -2,11 +2,19 @@ ## List +This function takes pagination parameters `page` and `per_page` to restrict the list of personal access tokens. + ``` GET /personal_access_tokens ``` -An example: +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `state` | string | no | filter tokens based on state (all, active, inactive) | + +Example response: ```json [ { @@ -20,20 +28,6 @@ An example: ] ``` -In addition, you can filter tokens based on state: `all`, `active` and `inactive` - -``` -GET /personal_access_tokens?state=all -``` - -``` -GET /personal_access_tokens?state=active -``` - -``` -GET /personal_access_tokens?state=inactive -``` - ## Show ``` diff --git a/doc/api/users.md b/doc/api/users.md index 2b4099227bc..91168c05dbe 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -831,18 +831,21 @@ Example response: ## Retrieve user personal access 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. ``` -GET /users/:user_id/personal_access_tokens +GET /users/:id/personal_access_tokens ``` Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `user_id` | integer | yes | The ID of the 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 | -An example: +Example response: ```json [ { @@ -852,45 +855,25 @@ An example: "expires_at": "2017-01-04", "scopes": ['api'], "active": true, - "impersonation": false, + "impersonation": true, "token": "9koXpg98eAheJpvBs5tK" } ] ``` -In addition, you can filter tokens based on state: `all`, `active` and `inactive` - -``` -GET /users/:user_id/personal_access_tokens?state=all -``` - -``` -GET /users/:user_id/personal_access_tokens?state=active -``` - -``` -GET /users/:user_id/personal_access_tokens?state=inactive -``` - -Finally, you can filter based on impersonation: `true` or `false`. - -``` -GET /users/:user_id/personal_access_tokens?impersonation=true -``` - ## Show a user personal access token It shows a user's personal access token. Note that only administrators can do this. ``` -GET /users/:user_id/personal_access_tokens/:personal_access_token_id +GET /users/:id/personal_access_tokens/:personal_access_token_id ``` Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `user_id` | integer | yes | The ID of the user | +| `id` | integer | yes | The ID of the user | | `personal_access_token_id` | integer | yes | The ID of the personal access token | ## Create a personal access token @@ -901,14 +884,14 @@ both API calls and Git reads and writes. The user will not see these tokens in h settings page. ``` -POST /users/:user_id/personal_access_tokens +POST /users/:id/personal_access_tokens ``` Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `user_id` | integer | yes | The ID of the user | +| `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 | @@ -919,12 +902,12 @@ Parameters: It revokes a personal access token. Note that only administrators can revoke impersonation tokens. ``` -DELETE /users/:user_id/personal_access_tokens/:personal_access_token_id +DELETE /users/:id/personal_access_tokens/:personal_access_token_id ``` Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `user_id` | integer | yes | The ID of the user | +| `id` | integer | yes | The ID of the user | | `personal_access_token_id` | integer | yes | The ID of the personal access token | -- cgit v1.2.1 From 005749a616c19b90d6ec0415df9ae5e35151e33c Mon Sep 17 00:00:00 2001 From: Tiago Botelho Date: Wed, 1 Mar 2017 16:59:03 +0000 Subject: apply codestyle and implementation changes to the respective feature code --- doc/api/README.md | 9 ++++- doc/api/personal_access_tokens.md | 69 --------------------------------------- doc/api/users.md | 60 ++++++++++++++++++++-------------- 3 files changed, 44 insertions(+), 94 deletions(-) delete mode 100644 doc/api/personal_access_tokens.md (limited to 'doc/api') 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 | -- cgit v1.2.1