Merge branch 'docs/personal-access-tokens' into 'master'9-3-stable-rc3-conflicts-docs

Add docs for personal access tokens

Closes #31740 and #33261

See merge request !12128

11 files changed, 162 insertions, 86 deletions

diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md
index affb4d17861..04c70c3644e 100644
--- a/doc/administration/raketasks/github_import.md
+++ b/doc/administration/raketasks/github_import.md
@@ -3,7 +3,7 @@
 >**Note:**
 >
 >  - [Introduced][ce-10308] in GitLab 9.1.
->  - You need a personal access token in order to retrieve and import GitHub 
+>  - You need a personal access token in order to retrieve and import GitHub
 >    projects. You can get it from: https://github.com/settings/tokens
 >  - You also need to pass an username as the second argument to the rake task
 >    which will become the owner of the project.
@@ -19,7 +19,7 @@ bundle exec rake import:github[access_token,root,foo/bar] RAILS_ENV=production
 ```
 
 In this case, `access_token` is your GitHub personal access token, `root`
-is your GitLab username, and  `foo/bar` is the new GitLab namespace/project that 
+is your GitLab username, and  `foo/bar` is the new GitLab namespace/project that
 will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`.
 
 
diff --git a/doc/api/README.md b/doc/api/README.md
index 2175b305e02..e7b48076ad1 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -55,6 +55,11 @@ following locations:
 - [V3 to V4](v3_to_v4.md)
 - [Version](version.md)
 
+The following documentation is for the [internal CI API](ci/README.md):
+
+- [Builds](ci/builds.md)
+- [Runners](ci/runners.md)
+
 ## Road to GraphQL
 
 API v4 will be the last REST API that we support. Going forward, we will start
@@ -63,20 +68,27 @@ endpoints. GraphQL has a number of benefits:
 
 1. We avoid having to maintain two different APIs.
 2. Callers of the API can request only what they need.
+<<<<<<< HEAD
 
 ### Internal CI API
+=======
+3. It is versioned by default.
 
-The following documentation is for the [internal CI API](ci/README.md):
-
-- [Builds](ci/builds.md)
-- [Runners](ci/runners.md)
+It will co-exist with the current v4 REST API. If we have a v5 API, this should
+be a compatibility layer on top of GraphQL.
+>>>>>>> f8740d5... Merge branch 'docs/personal-access-tokens' into 'master'
 
 ## Authentication
 
-Most API requests require authentication via a session cookie or token. For those cases where it is not required, this will be mentioned in the documentation 
-for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md). 
-There are three types of tokens available: private tokens, OAuth 2 tokens, and personal
-access tokens.
+Most API requests require authentication via a session cookie or token. For
+those cases where it is not required, this will be mentioned in the documentation
+for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md).
+
+There are three types of access tokens available:
+
+1. [OAuth2 tokens](#oauth2-tokens)
+1. [Private tokens](#private-tokens)
+1. [Personal access tokens](#personal-access-tokens)
 
 If authentication information is invalid or omitted, an error message will be
 returned with status code `401`:
@@ -87,20 +99,13 @@ returned with status code `401`:
 }
 ```
 
-### Session Cookie
+### 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
-header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
-an underscore). You can find or reset your private token in your account page
-(`/profile/account`).
-
-### OAuth 2 Tokens
+### OAuth2 tokens
 
 You can use an OAuth 2 token to authenticate with the API by passing it either in the
 `access_token` parameter or in the `Authorization` header.
@@ -113,30 +118,31 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api
 
 Read more about [GitLab as an OAuth2 client](oauth2.md).
 
-### Personal Access Tokens
+### Private tokens
 
-> [Introduced][ce-3749] in GitLab 8.8.
+Private tokens provide full access to the GitLab API. Anyone with access to
+them can interact with GitLab as if they were you. You can find or reset your
+private token in your account page (`/profile/account`).
 
-You can create as many personal access tokens as you like from your GitLab
-profile (`/profile/personal_access_tokens`); perhaps one for each application
-that needs access to the GitLab API.
+For examples of usage, [read the basic usage section](#basic-usage).
 
-Once you have your token, pass it to the API using either the `private_token`
-parameter or the `PRIVATE-TOKEN` header.
+### Personal access tokens
 
-> [Introduced][ce-5951] in GitLab 8.15.
+Instead of using your private token which grants full access to your account,
+personal access tokens could be a better fit because of their granular
+permissions.
 
-Personal Access Tokens can be created with one or more scopes that allow various actions
-that a given token can perform. Although there are only two scopes available at the
-moment – `read_user` and `api` – the groundwork has been laid to add more scopes easily.
+Once you have your token, pass it to the API using either the `private_token`
+parameter or the `PRIVATE-TOKEN` header. For examples of usage,
+[read the basic usage section](#basic-usage).
 
-At any time you can revoke any personal access token by just clicking **Revoke**.
+[Read more about personal access tokens.][pat]
 
 ### Impersonation tokens
 
 > [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions.
 
-Impersonation tokens are a type of [Personal Access Token](#personal-access-tokens)
+Impersonation tokens are a type of [personal access token][pat]
 that can only be created by an admin for a specific user.
 
 They are a better alternative to using the user's password/private token
@@ -145,9 +151,11 @@ 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.
 
-For more information about the usage please refer to the
+For more information, refer to the
 [users API](users.md#retrieve-user-impersonation-tokens) docs.
 
+For examples of usage, [read the basic usage section](#basic-usage).
+
 ### Sudo
 
 > Needs admin permissions.
@@ -200,11 +208,16 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
 ```
 
-## Basic Usage
+## 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].
 
+For endpoints that require [authentication](#authentication), you need to pass
+a `private_token` parameter via query string or header. If passed as a header,
+the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
+an underscore).
+
 Example of a valid API request:
 
 ```
@@ -217,6 +230,12 @@ Example of a valid API request using cURL and authentication via header:
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
 ```
 
+Example of a valid API request using cURL and authentication via a query string:
+
+```shell
+curl "https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK"
+```
+
 The API uses JSON to serialize data. You don't need to specify `.json` at the
 end of an API URL.
 
@@ -432,3 +451,4 @@ programming languages. Visit the [GitLab website] for a complete list.
 [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
+[pat]: ../user/profile/personal_access_tokens.md
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
index 46fe64d382e..07cb64cb373 100644
--- a/doc/api/oauth2.md
+++ b/doc/api/oauth2.md
@@ -134,4 +134,4 @@ access_token = client.password.get_token('user@example.com', 'secret')
 puts access_token.token
 ```
 
-[personal access tokens]: ./README.md#personal-access-tokens
\ No newline at end of file
+[personal access tokens]: ../user/profile/personal_access_tokens.md
diff --git a/doc/api/session.md b/doc/api/session.md
index 7dd504b67c5..f79eac11689 100644
--- a/doc/api/session.md
+++ b/doc/api/session.md
@@ -1,11 +1,9 @@
 # Session API
 
-## Deprecation Notice
-
-1. Starting in GitLab 8.11, this feature has been *disabled* for users with two-factor authentication turned on.
-2. These users can access the API using [personal access tokens] instead.
-
----
+>**Deprecation notice:**
+Starting in GitLab 8.11, this feature has been **disabled** for users with
+[two-factor authentication][2fa] turned on. These users can access the API
+using [personal access tokens] instead.
 
 You can login with both GitLab and LDAP credentials in order to obtain the
 private token.
@@ -52,4 +50,5 @@ Example response:
 }
 ```
 
-[personal access tokens]: ./README.md#personal-access-tokens
+[2fa]: ../user/profile/account/two_factor_authentication.md
+[personal access tokens]: ../user/profile/personal_access_tokens.md
diff --git a/doc/api/users.md b/doc/api/users.md
index f4167ba2605..91ce4f6dac3 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -804,7 +804,7 @@ Example response:
 
 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
+both API calls and Git reads and writes. The user will not see these tokens in their profile
 settings page.
 
 ```
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
index 408d46a756c..f7c2a0ef0ca 100644
--- a/doc/ci/docker/using_docker_build.md
+++ b/doc/ci/docker/using_docker_build.md
@@ -282,9 +282,9 @@ which can be avoided if a different driver is used, for example `overlay`.
 
 > **Notes:**
 - This feature requires GitLab 8.8 and GitLab Runner 1.2.
-- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
-  to pass a personal access token instead of your password in order to login to
-  GitLab's Container Registry.
+- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
+  to pass a [personal access token][pat] instead of your password in order to
+  login to GitLab's Container Registry.
 
 Once you've built a Docker image, you can push it up to the built-in
 [GitLab Container Registry](../../user/project/container_registry.md). For example,
@@ -409,3 +409,5 @@ Some things you should be aware of when using the Container Registry:
 
 [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
 [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
+[2fa]: ../../user/profile/account/two_factor_authentication.md
+[pat]: ../../user/profile/personal_access_tokens.md
diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md
index fb69d934ae1..590c3f862fb 100644
--- a/doc/user/profile/account/two_factor_authentication.md
+++ b/doc/user/profile/account/two_factor_authentication.md
@@ -125,23 +125,14 @@ applications and U2F devices.
 ## Personal access tokens
 
 When 2FA is enabled, you can no longer use your normal account password to
-authenticate with Git over HTTPS on the command line, you must use a personal
-access token instead.
-
-1. Log in to your GitLab account.
-1. Go to your **Profile Settings**.
-1. Go to **Access Tokens**.
-1. Choose a name and expiry date for the token.
-1. Click on **Create Personal Access Token**.
-1. Save the personal access token somewhere safe.
-
-When using Git over HTTPS on the command line, enter the personal access token
-into the password field.
+authenticate with Git over HTTPS on the command line or when using
+[GitLab's API][api], you must use a [personal access token][pat] instead.
 
 ## Recovery options
 
 To disable two-factor authentication on your account (for example, if you
 have lost your code generation device) you can:
+
 * [Use a saved recovery code](#use-a-saved-recovery-code)
 * [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh)
 * [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account)
@@ -154,8 +145,9 @@ codes. If you saved these codes, you can use one of them to sign in.
 To use a recovery code, enter your username/email and password on the GitLab
 sign-in page. When prompted for a two-factor code, enter the recovery code.
 
-> **Note:** Once you use a recovery code, you cannot re-use it. You can still
- use the other recovery codes you saved.
+>**Note:**
+Once you use a recovery code, you cannot re-use it. You can still use the other
+recovery codes you saved.
 
 ### Generate new recovery codes using SSH
 
@@ -190,11 +182,14 @@ a new set of recovery codes with SSH.
     two-factor code. Then, visit your Profile Settings and add a new device
     so you do not lose access to your account again.
     ```
-3. Go to the GitLab sign-in page and enter your username/email and password. When prompted for a two-factor code, enter one of the recovery codes obtained
-from the command-line output.
 
-> **Note:** After signing in, visit your **Profile Settings -> Account**  immediately to set up two-factor authentication with a new
-  device.
+3. Go to the GitLab sign-in page and enter your username/email and password.
+   When prompted for a two-factor code, enter one of the recovery codes obtained
+   from the command-line output.
+
+>**Note:**
+After signing in, visit your **Profile settings > Account**  immediately to set
+up two-factor authentication with a new device.
 
 ### Ask a GitLab administrator to disable two-factor authentication on your account
 
@@ -206,23 +201,23 @@ Sign in and re-enable two-factor authentication as soon as possible.
 ## Note to GitLab administrators
 
 - You need to take special care to that 2FA keeps working after
-[restoring a GitLab backup](../../../raketasks/backup_restore.md).
-
+  [restoring a GitLab backup](../../../raketasks/backup_restore.md).
 - To ensure 2FA authorizes correctly with TOTP server, you may want to ensure
-your GitLab server's time is synchronized via a service like NTP.  Otherwise,
-you may have cases where authorization always fails because of time differences.
-
-[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
-[FreeOTP]: https://freeotp.github.io/
-[YubiKey]: https://www.yubico.com/products/yubikey-hardware/
-
+  your GitLab server's time is synchronized via a service like NTP.  Otherwise,
+  you may have cases where authorization always fails because of time differences.
 - The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from
-multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at 
-the time of registration, and cannot be used for other hostnames/FQDNs.
+  multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at
+  the time of registration, and cannot be used for other hostnames/FQDNs.
 
     For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`:
 
     - The user logs in via `first.host.xyz` and registers their U2F key.
     - The user logs out and attempts to log in via `first.host.xyz` - U2F authentication suceeds.
-    - The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because 
+    - The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because
     the U2F key has only been registered on `first.host.xyz`.
+
+[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
+[FreeOTP]: https://freeotp.github.io/
+[YubiKey]: https://www.yubico.com/products/yubikey-hardware/
+[api]: ../../../api/README.md
+[pat]: ../personal_access_tokens.md
diff --git a/doc/user/profile/img/personal_access_tokens.png b/doc/user/profile/img/personal_access_tokens.png
new file mode 100644
index 00000000000..6aa63dbe342
--- /dev/null
+++ b/doc/user/profile/img/personal_access_tokens.png
diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md
new file mode 100644
index 00000000000..9488ce1ef30
--- /dev/null
+++ b/doc/user/profile/personal_access_tokens.md
@@ -0,0 +1,57 @@
+# Personal access tokens
+
+> [Introduced][ce-3749] in GitLab 8.8.
+
+Personal access tokens are useful if you need access to the [GitLab API][api].
+Instead of using your private token which grants full access to your account,
+personal access tokens could be a better fit because of their
+[granular permissions](#limiting-scopes-of-a-personal-access-token).
+
+You can also use them to authenticate against Git over HTTP. They are the only
+accepted method of authentication when you have
+[Two-Factor Authentication (2FA)][2fa] enabled.
+
+Once you have your token, [pass it to the API][usage] using either the
+`private_token` parameter or the `PRIVATE-TOKEN` header.
+
+## Creating a personal access token
+
+You can create as many personal access tokens as you like from your GitLab
+profile.
+
+1. Log in to your GitLab account.
+1. Go to your **Profile settings**.
+1. Go to **Access tokens**.
+1. Choose a name and optionally an expiry date for the token.
+1. Choose the [desired scopes](#limiting-scopes-of-a-personal-access-token).
+1. Click on **Create personal access token**.
+1. Save the personal access token somewhere safe. Once you leave or refresh
+   the page, you won't be able to access it again.
+
+![Personal access tokens page](img/personal_access_tokens.png)
+
+## Revoking a personal access token
+
+At any time, you can revoke any personal access token by just clicking the
+respective **Revoke** button under the 'Active personal access tokens' area.
+
+## Limiting scopes of a personal access token
+
+Personal access tokens can be created with one or more scopes that allow various
+actions that a given token can perform. The available scopes are depicted in
+the following table.
+
+| Scope | Description |
+| ----- | ----------- |
+|`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). |
+| `api` | Grants complete access to the API (read/write) ([introduced][ce-5951] in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. |
+| `read_registry` | Allows to read [container registry] images if a project is private and authorization is required ([introduced][ce-11845] in GitLab 9.3). |
+
+[2fa]: ../account/two_factor_authentication.md
+[api]: ../../api/README.md
+[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-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
+[container registry]: ../project/container_registry.md
+[users]: ../../api/users.md
+[usage]: ../../api/README.md#basic-usage
diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md
index 10c281448a3..c6862f48040 100644
--- a/doc/user/project/container_registry.md
+++ b/doc/user/project/container_registry.md
@@ -8,8 +8,8 @@
   Registry across your GitLab instance, visit the
   [administrator documentation](../../administration/container_registry.md).
 - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
-  to pass a personal access token instead of your password in order to login to
-  GitLab's Container Registry.
+  to pass a [personal access token][pat] instead of your password in order to
+  login to GitLab's Container Registry.
 - Multiple level image names support was added in GitLab 9.1
 
 With the Docker Container Registry integrated into GitLab, every project can
@@ -106,12 +106,11 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do
 
 ## Using with private projects
 
-If a project is private, credentials will need to be provided for authorization.
-The preferred way to do this, is by using personal access tokens, which can be
-created under `/profile/personal_access_tokens`. The minimal scope needed is:
-`read_registry`.
+> [Introduced][ce-11845] in GitLab 9.3.
 
-This feature was introduced in GitLab 9.3.
+If a project is private, credentials will need to be provided for authorization.
+The preferred way to do this, is by using [personal access tokens][pat].
+The minimal scope needed is `read_registry`.
 
 ## Troubleshooting the GitLab Container Registry
 
@@ -256,4 +255,6 @@ The solution: check the [IAM permissions again](https://docs.docker.com/registry
 Once the right permissions were set, the error will go away.
 
 [ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040
+[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
 [docker-docs]: https://docs.docker.com/engine/userguide/intro/
+[pat]: ../profile/personal_access_tokens.md
diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md
index e9512497d6c..271adee7da1 100644
--- a/doc/user/project/new_ci_build_permissions_model.md
+++ b/doc/user/project/new_ci_build_permissions_model.md
@@ -212,9 +212,9 @@ Container Registries for private projects.
   access token created explicitly for this purpose). This issue is resolved with
   latest changes in GitLab Runner 1.8 which receives GitLab credentials with
   build data.
-- Starting with GitLab 8.12, if you have 2FA enabled in your account, you need
-  to pass a personal access token instead of your password in order to login to
-  GitLab's Container Registry.
+- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
+  to pass a [personal access token][pat] instead of your password in order to
+  login to GitLab's Container Registry.
 
 Your jobs can access all container images that you would normally have access
 to. The only implication is that you can push to the Container Registry of the
@@ -239,3 +239,5 @@ test:
 [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update
 [workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse
 [jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables
+[2fa]: ../profile/account/two_factor_authentication.md
+[pat]: ../profile/personal_access_tokens.md