summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSean McGivern <sean@mcgivern.me.uk>2017-03-24 10:01:26 +0000
committerSean McGivern <sean@mcgivern.me.uk>2017-03-24 10:01:26 +0000
commit2965a20a1f5136c315cdfac19736e25690f5fcf6 (patch)
tree06bbde52192eccc57df0599be0ce2b205a553503
parentb1699ff7a49f4501e98fe85752a76a0a4745d116 (diff)
parentf4e7bc8377cf3a845494e5186086e183cd70e308 (diff)
downloadgitlab-ce-2965a20a1f5136c315cdfac19736e25690f5fcf6.tar.gz
Merge branch 'docs/update-impersonation-tokens' into 'master'
Update Impersonation tokens docs See merge request !10055
-rw-r--r--doc/api/README.md135
-rw-r--r--doc/api/users.md121
2 files changed, 165 insertions, 91 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 58d090b8f5e..e627b6f2ee8 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -74,6 +74,12 @@ returned with status code `401`:
}
```
+### Session Cookie
+
+When signing in to GitLab as an ordinary user, a `_gitlab_session` cookie is
+set. The API will use this cookie for authentication if it is present, but using
+the API to generate a new session cookie is currently not supported.
+
### Private Tokens
You need to pass a `private_token` parameter via query string or header. If passed as a
@@ -113,65 +119,25 @@ moment – `read_user` and `api` – the groundwork has been laid to add more sc
At any time you can revoke any personal access token by just clicking **Revoke**.
-### Session Cookie
+### Impersonation tokens
-When signing in to GitLab as an ordinary user, a `_gitlab_session` cookie is
-set. The API will use this cookie for authentication if it is present, but using
-the API to generate a new session cookie is currently not supported.
+> [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions.
-## Basic Usage
+Impersonation tokens are a type of [Personal Access Token](#personal-access-tokens)
+that can only be created by an admin for a specific user.
-API requests should be prefixed with `api` and the API version. The API version
-is defined in [`lib/api.rb`][lib-api-url].
+They are a better alternative to using the user's password/private token
+or using the [Sudo](#sudo) feature which also requires the admin's password
+or private token, since the password/token can change over time. Impersonation
+tokens are a great fit if you want to build applications or tools which
+authenticate with the API as a specific user.
-Example of a valid API request:
+For more information about the usage please refer to the
+[users API](users.md#retrieve-user-impersonation-tokens) docs.
-```shell
-GET https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK
-```
-
-Example of a valid API request using cURL and authentication via header:
-
-```shell
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
-```
-
-The API uses JSON to serialize data. You don't need to specify `.json` at the
-end of an API URL.
-
-## Status codes
-
-The API is designed to return different status codes according to context and
-action. This way, if a request results in an error, the caller is able to get
-insight into what went wrong.
-
-The following table gives an overview of how the API functions generally behave.
-
-| Request type | Description |
-| ------------ | ----------- |
-| `GET` | Access one or more resources and return the result as JSON. |
-| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
-| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
-| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. |
-
-The following table shows the possible return codes for API requests.
-
-| Return values | Description |
-| ------------- | ----------- |
-| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
-| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
-| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
-| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
-| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
-| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
-| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. |
-| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. |
-| `405 Method Not Allowed` | The request is not supported. |
-| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. |
-| `422 Unprocessable` | The entity could not be processed. |
-| `500 Server Error` | While handling the request something went wrong server-side. |
+### Sudo
-## Sudo
+> Needs admin permissions.
All API requests support performing an API call as if you were another user,
provided your private token is from an administrator account. You need to pass
@@ -202,7 +168,7 @@ returned with status code `404`:
Example of a valid API call and a request using cURL with sudo request,
providing a username:
-```shell
+```
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
```
@@ -213,7 +179,7 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "h
Example of a valid API call and a request using cURL with sudo request,
providing an ID:
-```shell
+```
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
```
@@ -221,13 +187,57 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
```
-## Impersonation Tokens
+## Basic Usage
+
+API requests should be prefixed with `api` and the API version. The API version
+is defined in [`lib/api.rb`][lib-api-url].
+
+Example of a valid API request:
+
+```
+GET /projects?private_token=9koXpg98eAheJpvBs5tK
+```
+
+Example of a valid API request using cURL and authentication via header:
+
+```shell
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
+```
+
+The API uses JSON to serialize data. You don't need to specify `.json` at the
+end of an API URL.
+
+## Status codes
+
+The API is designed to return different status codes according to context and
+action. This way, if a request results in an error, the caller is able to get
+insight into what went wrong.
+
+The following table gives an overview of how the API functions generally behave.
+
+| Request type | Description |
+| ------------ | ----------- |
+| `GET` | Access one or more resources and return the result as JSON. |
+| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
+| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
+| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. |
-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.
+The following table shows the possible return codes for API requests.
-For more information about the usage please refer to the [Users](users.md) page
+| Return values | Description |
+| ------------- | ----------- |
+| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
+| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
+| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
+| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
+| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
+| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
+| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. |
+| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. |
+| `405 Method Not Allowed` | The request is not supported. |
+| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. |
+| `422 Unprocessable` | The entity could not be processed. |
+| `500 Server Error` | While handling the request something went wrong server-side. |
## Pagination
@@ -307,14 +317,14 @@ For example, an issue might have `id: 46` and `iid: 5`.
That means that if you want to get an issue via the API you should use the `id`:
-```bash
+```
GET /projects/42/issues/:id
```
On the other hand, if you want to create a link to a web page you should use
the `iid`:
-```bash
+```
GET /projects/42/issues/:iid
```
@@ -398,3 +408,4 @@ programming languages. Visit the [GitLab website] for a complete list.
[lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
+[ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099
diff --git a/doc/api/users.md b/doc/api/users.md
index 14b5c6c713e..2ada4d09c84 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -828,10 +828,12 @@ Example response:
]
```
-## Retrieve user impersonation tokens
+## Get all impersonation tokens of a user
-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.
+> Requires admin permissions.
+
+It retrieves every impersonation token of the user. Use the pagination
+parameters `page` and `per_page` to restrict the list of impersonation tokens.
```
GET /users/:user_id/impersonation_tokens
@@ -842,27 +844,50 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `user_id` | integer | yes | The ID of the user |
-| `state` | string | no | filter tokens based on state (all, active, inactive) |
+| `state` | string | no | filter tokens based on state (`all`, `active`, `inactive`) |
+
+```
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
+```
Example response:
+
```json
[
- {
- "id": 1,
- "name": "mytoken",
- "revoked": false,
- "expires_at": "2017-01-04",
- "scopes": ['api'],
- "active": true,
- "impersonation": true,
- "token": "9koXpg98eAheJpvBs5tK"
- }
+ {
+ "active" : true,
+ "token" : "EsMo-vhKfXGwX9RKrwiy",
+ "scopes" : [
+ "api"
+ ],
+ "revoked" : false,
+ "name" : "mytoken",
+ "id" : 2,
+ "created_at" : "2017-03-17T17:18:09.283Z",
+ "impersonation" : true,
+ "expires_at" : "2017-04-04"
+ },
+ {
+ "active" : false,
+ "scopes" : [
+ "read_user"
+ ],
+ "revoked" : true,
+ "token" : "ZcZRpLeEuQRprkRjYydY",
+ "name" : "mytoken2",
+ "created_at" : "2017-03-17T17:19:28.697Z",
+ "id" : 3,
+ "impersonation" : true,
+ "expires_at" : "2017-04-14"
+ }
]
```
-## Show a user's impersonation token
+## Get an impersonation token of a user
-It shows a user's impersonation token. Note that only administrators can do this.
+> Requires admin permissions.
+
+It shows a user's impersonation token.
```
GET /users/:user_id/impersonation_tokens/:impersonation_token_id
@@ -875,7 +900,31 @@ Parameters:
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
-## Create a impersonation token
+```
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
+```
+
+Example response:
+
+```json
+{
+ "active" : true,
+ "token" : "EsMo-vhKfXGwX9RKrwiy",
+ "scopes" : [
+ "api"
+ ],
+ "revoked" : false,
+ "name" : "mytoken",
+ "id" : 2,
+ "created_at" : "2017-03-17T17:18:09.283Z",
+ "impersonation" : true,
+ "expires_at" : "2017-04-04"
+}
+```
+
+## Create an impersonation token
+
+> Requires admin permissions.
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
@@ -891,32 +940,46 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `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) |
+| `name` | string | yes | The name of the impersonation token |
+| `expires_at` | date | no | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)|
+| `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user`) |
+
+```
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
+```
Example response:
+
```json
{
- "id": 1,
- "name": "mytoken",
- "revoked": false,
- "expires_at": "2017-01-04",
- "scopes": ['api'],
- "active": true,
- "impersonation": true,
- "token": "9koXpg98eAheJpvBs5tK"
+ "id" : 2,
+ "revoked" : false,
+ "scopes" : [
+ "api"
+ ],
+ "token" : "EsMo-vhKfXGwX9RKrwiy",
+ "active" : true,
+ "impersonation" : true,
+ "name" : "mytoken",
+ "created_at" : "2017-03-17T17:18:09.283Z",
+ "expires_at" : "2017-04-04"
}
```
## Revoke an impersonation token
-It revokes an impersonation token. Note that only administrators can revoke impersonation tokens.
+> Requires admin permissions.
+
+It revokes an impersonation token.
```
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
```
+```
+curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1
+```
+
Parameters:
| Attribute | Type | Required | Description |