debian-mirror-gitlab/doc/user/profile/personal_access_tokens.md

type
concepts, howto

Personal access tokens

• Introduced in GitLab 8.8.
• Notifications about expiring tokens added in GitLab 12.6.
• Token lifetime limits added in GitLab Ultimate 12.6.

If you're unable to use OAuth2, you can use a personal access token to authenticate with the GitLab API.

You can also use personal access tokens with Git to authenticate over HTTP or SSH. Personal access tokens are required when Two-Factor Authentication (2FA) is enabled. In both cases, you can authenticate with a token in place of your password.

Personal access tokens expire on the date you define, at midnight UTC.

• GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that will expire in under seven days. The owners of these tokens are notified by email.
• In GitLab Ultimate, administrators may limit the lifetime of personal access tokens.

For examples of how you can use a personal access token to authenticate with the API, see the following section from our API Docs.

GitLab also offers impersonation tokens which are created by administrators via the API. They're a great fit for automated authentication as a specific user.

Creating a personal access token

You can create as many personal access tokens as you like from your GitLab profile.

1. Log in to GitLab.
2. In the upper-right corner, click your avatar and select Settings.
3. On the User Settings menu, select Access Tokens.
4. Choose a name and optional expiry date for the token.
5. Choose the desired scopes.
6. Click the Create personal access token button.
7. Save the personal access token somewhere safe. Once you leave or refresh the page, you won't be able to access it again.

Revoking a personal access token

At any time, you can revoke any personal access token by clicking the respective Revoke button under the Active Personal Access Token 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	Introduced in	Description
read_user	GitLab 8.15	Allows access to the read-only endpoints under /users. Essentially, any of the GET requests in the Users API are allowed.
api	GitLab 8.15	Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry.
read_api	GitLab 12.10	Grants read access to the API, including all groups and projects, the container registry, and the package registry.
read_registry	GitLab 9.3	Allows to read (pull) container registry images if a project is private and authorization is required.
sudo	GitLab 10.2	Allows performing API actions as any user in the system (if the authenticated user is an admin).
read_repository	GitLab 10.7	Allows read-only access (pull) to the repository through git clone.
write_repository	GitLab 11.11	Allows read-write access (pull, push) to the repository through git clone. Required for accessing Git repositories over HTTP when 2FA is enabled.