diff options
author | Douwe Maan <douwe@selenight.nl> | 2017-03-07 18:29:55 +0300 |
---|---|---|
committer | Douwe Maan <douwe@selenight.nl> | 2017-03-07 18:29:55 +0300 |
commit | 6a52cda31da4becc3e342530a2bdf0868d8921cc (patch) | |
tree | c1dda64455fb29597100513596ae02f1d1946089 /doc | |
parent | 61cfe6dea6f2d6725771a0f341e70975cf91c7f7 (diff) | |
parent | 005749a616c19b90d6ec0415df9ae5e35151e33c (diff) |
Merge remote-tracking branch 'origin/personal_access_token_api_and_impersonation_token'
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/README.md | 8 | ||||
-rw-r--r-- | doc/api/users.md | 96 |
2 files changed, 104 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 45048294298..58d090b8f5e 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -221,6 +221,14 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/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/users.md b/doc/api/users.md index 95f6bcfccb6..14b5c6c713e 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -827,3 +827,99 @@ Example response: } ] ``` + +## Retrieve user impersonation 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/:user_id/impersonation_tokens +``` + +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) | + +Example response: +```json +[ + { + "id": 1, + "name": "mytoken", + "revoked": false, + "expires_at": "2017-01-04", + "scopes": ['api'], + "active": true, + "impersonation": true, + "token": "9koXpg98eAheJpvBs5tK" + } +] +``` + +## Show a user's impersonation token + +It shows a user's impersonation token. Note that only administrators can do this. + +``` +GET /users/:user_id/impersonation_tokens/:impersonation_token_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `user_id` | integer | yes | The ID of the user | +| `impersonation_token_id` | integer | yes | The ID of the impersonation token | + +## Create a impersonation token + +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/:user_id/impersonation_tokens +``` + +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) | + +Example response: +```json +{ + "id": 1, + "name": "mytoken", + "revoked": false, + "expires_at": "2017-01-04", + "scopes": ['api'], + "active": true, + "impersonation": true, + "token": "9koXpg98eAheJpvBs5tK" +} +``` + +## Revoke an impersonation token + +It revokes an impersonation token. Note that only administrators can revoke impersonation tokens. + +``` +DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `user_id` | integer | yes | The ID of the user | +| `impersonation_token_id` | integer | yes | The ID of the impersonation token | |