Skip to content

Personal access tokens

Introduced in GitLab 8.8.

Personal access tokens are the preferred way for third party applications and scripts to authenticate with the GitLab API, if using OAuth2 is not practical.

You can also use personal access tokens to authenticate against Git over HTTP or SSH. They must be used when you have Two-Factor Authentication (2FA) enabled. Authenticate with a token in place of your password.

To make authenticated requests to the API, use either the private_token parameter or the Private-Token header.

The expiration of personal access tokens happens on the date you define, at midnight UTC.

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 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][ce-5951] in GitLab 8.15).
api Grants complete access to the API and Container Registry (read/write) (introduced in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled.
read_registry Allows to read (pull) container registry images if a project is private and authorization is required (introduced in GitLab 9.3).
sudo Allows performing API actions as any user in the system (if the authenticated user is an admin) (introduced in GitLab 10.2).
read_repository Allows read-access (pull) to the repository through git clone.