Personal access tokens

Version history

Introduced in GitLab 8.8.
Notifications for expiring tokens added in GitLab 12.6.
Token lifetime limits added in GitLab Ultimate 12.6.
Additional notifications for expiring tokens added in GitLab 13.3.

If you’re unable to use OAuth2, you can use a personal access token to authenticate with the GitLab API. You can also use a personal access token with Git to authenticate over HTTP.

In both cases, you authenticate with a personal access token in place of your password.

Personal access tokens are required when Two-Factor Authentication (2FA) is enabled.

For examples of how you can use a personal access token to authenticate with the API, see the API documentation.

Alternately, GitLab administrators can use the API to create impersonation tokens. Use impersonation tokens to automate authentication as a specific user.

Create a personal access token

You can create as many personal access tokens as you like.

In the top-right corner, select your avatar.
Select Edit profile.
In the left sidebar, select Access Tokens.
Enter a name and optional expiry date for the token.
Select the desired scopes.
Select Create personal access token.

Save the personal access token somewhere safe. After you leave the page, you no longer have access to the token.

Revoke a personal access token

At any time, you can revoke a personal access token.

In the top-right corner, select your avatar.
Select Edit profile.
In the left sidebar, select Access Tokens.
In the Active personal access tokens area, next to the key, select Revoke.

View the last time a token was used

Token usage is updated once every 24 hours. It is updated each time the token is used to request API resources and the GraphQL API.

To view the last time a token was used:

In the top-right corner, select your avatar.
Select Edit profile.
In the left sidebar, select Access Tokens.
In the Active personal access tokens area, next to the key, view the Last Used date.

Personal access token scopes

A personal access token can perform actions based on the assigned scopes.

Scope	Introduced in	Access
`api`	8.15	Read-write for the complete API, including all groups and projects, the Container Registry, and the Package Registry.
`read_user`	8.15	Read-only for endpoints under `/users`. Essentially, access to any of the `GET` requests in the Users API.
`read_api`	12.10	Read-only for the complete API, including all groups and projects, the Container Registry, and the Package Registry.
`read_repository`	10.7	Read-only (pull) for the repository through `git clone`.
`write_repository`	11.11	Read-write (pull, push) for the repository through `git clone`. Required for accessing Git repositories over HTTP when 2FA is enabled.
`read_registry`	9.3	Read-only (pull) for Container Registry images if a project is private and authorization is required.
`write_registry`	12.10	Read-write (push) for Container Registry images if a project is private and authorization is required.
`sudo`	10.2	API actions as any user in the system (if the authenticated user is an administrator).

When personal access tokens expire

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 expire in the next seven days. The owners of these tokens are notified by email.
GitLab runs a check at 02:00 AM UTC every day to identify personal access tokens that expire on the current date. The owners of these tokens are notified by email.
In GitLab Ultimate, administrators can limit the lifetime of personal access tokens.
In GitLab Ultimate, administrators can choose whether or not to enforce personal access token expiration.

Create a personal access token programmatically

You can create a predetermined personal access token as part of your tests or automation.

Prerequisite:

You need sufficient access to run a Rails console session for your GitLab instance.

To create a personal access token programmatically:

Open a Rails console:
```
sudo gitlab-rails console
```
Run the following commands to reference the username, the token, and the scopes.
The token must be 20 characters long. The scopes must be valid and are visible in the source code.
For example, to create a token that belongs to a user with username automation-bot:
```
user = User.find_by_username('automation-bot')
token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token')
token.set_token('token-string-here123')
token.save!
```

This code can be shortened into a single-line shell command by using the Rails runner:

sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!"

Revoke a personal access token programmatically

You can programmatically revoke a personal access token as part of your tests or automation.

Prerequisite:

You need sufficient access to run a Rails console session for your GitLab instance.

To revoke a token programmatically:

Open a Rails console:
```
sudo gitlab-rails console
```

To revoke a token of token-string-here123, run the following commands:

token = PersonalAccessToken.find_by_token('token-string-here123')
token.revoke!

This code can be shortened into a single-line shell command using the Rails runner:

sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"