gitlab-org--gitlab-foss/doc/user/profile/personal_access_tokens.md
2017-06-14 08:40:21 +02:00

2.6 KiB

Personal access tokens

Introduced in GitLab 8.8.

Personal access tokens are useful if you need access to the GitLab 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.

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) enabled.

Once you have your token, pass it to the API 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.
  2. Go to your Profile settings.
  3. Go to Access tokens.
  4. Choose a name and optionally an expiry date for the token.
  5. Choose the desired scopes.
  6. Click on Create personal access token.
  7. 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

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 are allowed (introduced in GitLab 8.15).
api Grants complete access to the API (read/write) (introduced 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 in GitLab 9.3).