doc/user/profile/personal_access_tokens.md
{{< details >}}
{{< /details >}}
Personal access tokens provide authenticated access to GitLab. They are an alternative to OAuth2 tokens and are similar to group access tokens and project access tokens, but are attached to a user rather than a group or project.
You can use a personal access token to authenticate:
[!note] You must authenticate with a personal access token if two-factor authentication (2FA) or SAML is enabled.
Some GitLab features that require a username, like the GitLab-managed Terraform state backend and the container registry, use a personal access token with a GitLab username. In these cases, the username is required but is not evaluated as part of authentication. For more information, see issue 212953.
On GitLab Self-Managed and GitLab Dedicated instances, administrators can use the user tokens API to create impersonation tokens to authenticate as a specific user.
{{< history >}}
pat_ip. Enabled by default in 17.9.pat_ip removed.{{< /history >}}
The personal access tokens page displays information about your access tokens.
From this page, you can perform the following actions:
[!note] GitLab periodically updates token usage information when the token performs a Git operation or authenticates an operation with the REST or GraphQL API. Token usage times are updated every 10 minutes, token usage IP addresses update every minute.
To view your personal access tokens:
Select the name of a token to open the details panel. By default, only active tokens are displayed. Use the search bar to filter the list of access tokens.
{{< history >}}
buffered_token_expiration_limit. Disabled by default.{{< /history >}}
[!flag] The availability of the extended maximum allowable lifetime limit is controlled by a feature flag. For more information, see the history.
To create a personal access token:
A personal access token is displayed. Save the personal access token somewhere safe. After you leave or refresh the page, you cannot view it again.
All access tokens inherit the default prefix setting configured for personal access tokens.
You can prefill the details of the personal access token by appending the name, description, and list of scopes to the URL. For example:
https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&description=My+description&scopes=api,read_user
[!note] Personal access tokens must be treated carefully. For guidance on managing personal access tokens, see token security considerations.
{{< history >}}
k8s_proxy introduced in GitLab 16.4 with a flag named k8s_proxy_pat. Enabled by default.k8s_proxy_pat removed in GitLab 16.5.read_service_ping introduced in GitLab 17.1.manage_runner introduced in GitLab 17.1.self_rotate introduced in GitLab 17.9. Enabled by default.{{< /history >}}
Scopes define the actions available when you authenticate with a personal access token. The following scopes are available:
[!note] Fine-grained personal access tokens use different scopes.
| Scope | Description |
|---|---|
api | Grants complete read and write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry. Also grants complete read and write access to the registry and repository using Git-over-HTTP. |
read_api | Grants read access to the API, including all groups and projects, the container registry, and the package registry. |
read_registry | Grants read access (pull) to container registry images if a project is private and authorization is required. Available only when the container registry is enabled. |
write_registry | Grants write access (push) to container registry images if a project is private and authorization is required. Available only when the container registry is enabled. |
read_virtual_registry | Grants read access (pull) to container images through the dependency proxy if a project is private and authorization is required. Available only when the dependency proxy is enabled. |
write_virtual_registry | Grants read and write access (pull, push, and delete) to container images through the dependency proxy if a project is private and authorization is required. Available only when the dependency proxy is enabled. |
read_repository | Grants read access (pull) to repositories on private projects using Git-over-HTTP or the repository files API. |
write_repository | Grants read and write access (pull and push) to repositories on private projects using Git-over-HTTP. Does not support API authentication. |
create_runner | Grants permission to create runners. |
manage_runner | Grants permission to manage runners. |
admin_mode | Grants permission to perform API actions when Admin Mode is enabled. Available only to administrators on GitLab Self-Managed instances. |
ai_features | Grants permission to perform API actions for GitLab Duo, the Code Suggestions API, and the GitLab Duo Chat API. Designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see the individual extension documentation. Does not work for GitLab Self-Managed versions 16.5, 16.6, and 16.7. |
k8s_proxy | Grants permission to perform Kubernetes API calls using the agent for Kubernetes. |
self_rotate | Grants permission to rotate this token using the personal access token API. Does not allow rotation of other tokens. |
read_service_ping | Grants access to download the Service Ping payloads through the API when authenticated as an administrator. |
sudo | Grants permission to perform API actions as any user in the system, when authenticated as an administrator. |
read_user | Grants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users. |
[!warning] If you have enabled external authorization, personal access tokens cannot access container or package registries. To restore access, turn off external authorization.
{{< history >}}
{{< /history >}}
Rotate a token to create a new token with the same permissions and scope as the original. The original token becomes inactive immediately, and GitLab retains both versions for audit purposes.
[!warning] This action cannot be undone. Tools that rely on a rotated access token will stop working until you reference your new token.
To rotate a personal access token:
{{< history >}}
{{< /history >}}
Revoke a token to immediately invalidate it and prevent further use. GitLab retains the token for audit purposes. You cannot permanently delete tokens, but you can filter token lists to show only active tokens.
[!warning] This action cannot be undone. Tools that rely on a revoked access token will stop working until you add a new token.
To revoke a personal access token:
Personal, group, and project access tokens expire at midnight UTC on the expiry date. After they expire, they can no longer be used to authenticate requests.
In GitLab 16.0 and later, new access tokens must have an expiry date. If an expiry date isn't explicitly set during token creation, an expiry date of 365 days from the current date is applied. In GitLab Ultimate, administrators can configure a maximum allowable lifetime for access tokens.
Depending on your GitLab version and offering, your existing access tokens might have an expiry date automatically applied when upgrading GitLab versions. For more information, see non-expiring access tokens.
{{< history >}}
expiring_pats_30d_60d_notifications. Disabled by default.expiring_pats_30d_60d_notifications removed.{{< /history >}}
GitLab runs a daily check at 1:00 AM UTC to identify personal access tokens that expire soon. Users are notified by email seven days before a token expires. In GitLab 17.6 and later, notifications are also sent 30 and 60 days before a token expires.
You can subscribe to an iCalendar endpoint which contains events at the expiry date for each token. After signing in, this endpoint is available at /-/user_settings/personal_access_tokens.ics.
You can create a personal access token for a service account with no expiry date. These personal access tokens never expire, unlike non-service account personal access tokens.
[!note] Allowing personal access tokens for service accounts to be created with no expiry date only affects tokens created after you change this setting. It does not affect existing tokens.
Prerequisites:
You can now create personal access tokens for a service account user with no expiry date.
Prerequisites:
You can now create personal access tokens for a service account user with no expiry date.
{{< details >}}
{{< /details >}}
{{< history >}}
Disable access tokens setting in GitLab 17.3.{{< /history >}}
Prerequisites:
You can prevent users from authenticating with access tokens across your entire GitLab instance. This setting affects personal access tokens, group access tokens, project access tokens, and impersonation tokens. This setting also applies to personal access tokens for service accounts.
When you disable access tokens, the following rules apply:
404 Not Found error.To disable access tokens for the instance:
You can also use the disable_personal_access_tokens attribute in the application settings API.
{{< details >}}
{{< /details >}}
{{< history >}}
enterprise_disable_personal_access_tokens. Disabled by default.enterprise_disable_personal_access_tokens removed.{{< /history >}}
Prerequisites:
Disabling the personal access tokens of a group's enterprise users:
[!warning] Disabling personal access tokens for enterprise users does not disable personal access tokens for service accounts.
To disable the enterprise users' personal access tokens:
When you delete or block an enterprise user account, their personal access tokens are automatically revoked.
{{< details >}}
{{< /details >}}
{{< history >}}
dpop_authentication. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
Demonstrating Proof of Possession (DPoP) enhances the security of your personal access tokens, and minimizes the effects of unintended token leaks. When you enable this feature on your account, all REST and GraphQL API requests containing a PAT must also provide a signed DPoP header. Creating a signed DPoP header requires your corresponding private SSH key.
[!note] If you enable this feature, all API requests without a valid DPoP header return a
DpopValidationErrorerror.DPoP header is not required for Git operations over HTTPS that include an access token.
Prerequisites:
To require DPoP on all calls to the REST and GraphQL APIs:
In the upper-right corner, select your avatar.
Select Edit profile.
In the left sidebar, select Access > Personal access tokens.
Go to the Use Demonstrating Proof of Possession (DPoP) section, and select Enable DPoP.
Select Save changes.
To generate a DPoP header with the GitLab CLI,
run this command in your terminal. Replace <your_access_token> with your access token, and ~/.ssh/id_rsa
with the location of your private key:
glab auth dpop-gen --pat "<your_access_token>" --private-key ~/.ssh/id_rsa
The DPoP header you generated in the CLI can be used:
With the REST API:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--header "DPoP: <dpop-from-glab>" \
"https://gitlab.example.com/api/v4/projects"
With GraphQL:
curl --request POST \
--header "Content-Type: application/json" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "DPoP: <dpop-from-glab>" \
--data '{
"query": "query { currentUser { id } }"
}' \
"https://gitlab.example.com/api/graphql"
To learn more about DPoP, see the blueprint Sender Constraining Personal Access Tokens.
{{< details >}}
{{< /details >}}
You can create a predetermined personal access token as part of your tests or automation.
Prerequisites:
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 and expires in a year:
user = User.find_by_username('automation-bot')
token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now)
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', expires_at: 365.days.from_now); token.set_token('token-string-here123'); token.save!"
{{< details >}}
{{< /details >}}
You can programmatically revoke a personal access token as part of your tests or automation.
Prerequisites:
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!"
{{< details >}}
{{< /details >}}
To clone a repository when SSH is disabled, clone it using a personal access token by running the following command:
git clone https://<username>:<personal_token>@gitlab.com/gitlab-org/gitlab.git
This method saves your personal access token in your bash history. To avoid this, run the following command:
git clone https://<username>@gitlab.com/gitlab-org/gitlab.git
When asked for your password for https://gitlab.com, enter your personal access token.
The username in the clone command:
Remember this if you set up an automation pipeline that depends on authentication.
For Git over HTTPS, an alternative to personal access tokens is to use an OAuth credential helper.
For authentication in CI/CD jobs, consider: