Project access tokens

Tier: Free, Premium, Ultimate Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Introduced for trial subscriptions in GitLab 16.1.

Project access tokens provide authenticated access to a specific project. They are similar to group access tokens and personal access tokens, but are scoped to the associated project rather than a group or user. You cannot use project access tokens to access resources in other projects, or to create other group, project, or personal access tokens.

You can use a project access token to authenticate:

With the GitLab API.
With Git over HTTPS. Use:
- Any non-blank value as a username.
- The project access token as the password.

Prerequisites:

The Maintainer or Owner role for the project.

[!note] On GitLab.com, project access tokens require a Premium or Ultimate subscription. During a trial, you are limited to one project access token.

On GitLab Self-Managed and GitLab Dedicated, project access tokens are available with any license.

View your access tokens

In GitLab 16.0 and earlier, token usage information is updated every 24 hours.
The frequency of token usage information updates changed in GitLab 16.1 from 24 hours to 10 minutes.
Ability to view IP addresses introduced in GitLab 17.8 with a flag named pat_ip. Enabled by default in 17.9.
Ability to view IP addresses made generally available in GitLab 17.10. Feature flag pat_ip removed.

The project access tokens page displays information about your access tokens.

From this page, you can perform the following actions:

Create, rotate, and revoke project access tokens.
View all active and inactive project access tokens.
View token information, including, scopes, assigned roles, and expiration dates.
View usage information, including usage dates, and of the last five distinct connection IP addresses.

[!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 project access tokens:

In the top bar, select Search or go to and find your project.
Select Settings > Access tokens.

Active and usable access tokens are stored in the Active project access tokens section. Expired, rotated, or revoked tokens are stored in the Inactive project access tokens section.

Create a project access token

Ability to create non-expiring project access tokens was removed in GitLab 16.0.
Maximum allowable lifetime limit extended to 400 days in GitLab 17.6 with a flag named buffered_token_expiration_limit. Disabled by default.
Project access token description introduced in GitLab 17.7.

[!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 project access token:

In the top bar, select Search or go to and find your project.
Select Settings > Access tokens.
Select Add new token.
In Token name, enter a name. The token name is visible to any user with permissions to view the project.
Optional. In Token description, enter a description for the token.
In Expiration date, enter an expiry date for the token.
- The token expires at midnight UTC on that date.
- If you do not enter a date, the expiry date is set to 365 days from today.
- By default, the expiry date cannot be more than 365 days from today. On GitLab 17.6 and later, administrators can modify the maximum lifetime of access tokens.
Select a role for the token.
Select one or more project access token scopes.
Select Create project access token.

A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you cannot view it again.

All project access tokens inherit the default prefix setting configured for personal access tokens.

[!warning] Project access tokens are treated as internal users. If an internal user creates a project access token, that token can access all projects that have visibility level set to Internal.

Project access token scopes

k8s_proxy introduced in GitLab 16.4 with a flag named k8s_proxy_pat. Enabled by default.
Feature flag k8s_proxy_pat removed in GitLab 16.5.
self_rotate introduced in GitLab 17.9. Enabled by default.

Scopes define the actions available when you authenticate with a project access token.

Scope	Description
`api`	Grants complete read and write access to the scoped project API, including the container registry, the dependency proxy, and the package registry.
`read_api`	Grants read access to the scoped project API, including the package registry.
`read_registry`	Grants read access (pull) to container registry images if the project is private and authorization is required. Available only when the container registry is enabled.
`write_registry`	Grants write access (push) to the container registry. To push images, you must include the `read_registry` scope. Available only when the container registry is enabled.
`read_repository`	Grants read access (pull) to the repository in the project.
`write_repository`	Grants read and write access (pull and push) to the repository in the project.
`create_runner`	Grants permission to create runners in the project.
`manage_runner`	Grants permission to manage runners in the project.
`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 in the project.
`self_rotate`	Grants permission to rotate this token using the personal access token API. Does not allow rotation of other tokens.

[!warning] If you have enabled external authorization, personal access tokens cannot access container or package registries. To restore access, turn off external authorization.

Rotate a project access token

Ability to view expired and revoked tokens introduced in GitLab 17.3 with a flag named retain_resource_access_token_user_after_revoke. Disabled by default.
Ability to view expired and revoked tokens until they are automatically deleted generally available in GitLab 17.9. Feature flag retain_resource_access_token_user_after_revoke removed.

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. You can view both active and inactive tokens on the access tokens page.

On GitLab Self-Managed and GitLab Dedicated, you can modify the retention period for inactive tokens.

[!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 project access token:

In the top bar, select Search or go to and find your project.
Select Settings > Access tokens.
For the relevant token, select Rotate ({{< icon name="retry" >}}).
In the confirmation dialog, select Rotate.

Revoke a project access token

Ability to view expired and revoked tokens introduced in GitLab 17.3 with a flag named retain_resource_access_token_user_after_revoke. Disabled by default.
Ability to view expired and revoked tokens until they are automatically deleted generally available in GitLab 17.9. Feature flag retain_resource_access_token_user_after_revoke removed.

Revoke a token to immediately invalidate it and prevent further use. Revoked tokens are not deleted immediately, but you can filter token lists to show only active tokens. By default, GitLab deletes revoked group and project access tokens after 30 days. For more information, see inactive token retention.

[!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 project access token:

In the top bar, select Search or go to and find your project.
Select Settings > Access tokens.
For the relevant token, select Revoke ({{< icon name="remove" >}}).
In the confirmation dialog, select Revoke.

Access token expiration

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.

Project access token expiry emails

60 and 30 day expiry notifications introduced in GitLab 17.6 with a flag named expiring_pats_30d_60d_notifications. Disabled by default.
60 and 30 day notifications generally available in GitLab 17.7. Feature flag expiring_pats_30d_60d_notifications removed.
Notifications to inherited group members introduced in GitLab 17.7 with a flag named pat_expiry_inherited_members_notification. Disabled by default.
Feature flag pat_expiry_inherited_members_notification enabled by default in GitLab 17.10.
Feature flag pat_expiry_inherited_members_notification removed in GitLab 17.11

GitLab runs a daily check at 1:00 AM UTC to identify project access tokens that expire soon. Direct members with the Owner or Maintainer role 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.

In GitLab 17.7 and later, members with an inherited Owner or Maintainer role can also receive these emails. You can configure this for every group and project on the GitLab instance or a specific parent group. If applied to a parent group, this setting is inherited by all descendant groups and projects.

Expired tokens appear in the inactive project access tokens section until they're automatically deleted. On GitLab Self-Managed, you can modify this retention period.

Bot users for projects

Changed in GitLab 17.2 with a flag named retain_resource_access_token_user_after_revoke. Disabled by default. When enabled new bot users are made members with no expiry date and, when the token is later revoked or expires, the bot user is retained for 30 days.
Inactive bot users retention is generally available in GitLab 17.9. Feature flag retain_resource_access_token_user_after_revoke removed.

When you create a project access token, GitLab creates a bot user and associates it with the token.

Bot users have the following properties:

They are granted permissions that correspond with the role and scope of the associated access token.
They are members of the project, but cannot be removed from the project or added directly to any other groups or projects.
They are non-billable users and do not count towards your license limit.
Their contributions are associated with the bot user account.
When removed, their contributions are moved to a ghost user.

When the bot user is created, the following attributes are defined:

Attribute	Value	Example
Name	The name of the associated access token.	`Main token - Read registry`
Username	Generated in this format: `project_{project_id}_bot_{random_string}`	`project_123_bot_4ffca233d8298ea1`
Email	Generated in this format: `project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}`	`[email protected]`

Restrict the creation of project access tokens

To limit potential abuse, you can restrict users from creating access tokens for projects in a top-level group. Any existing tokens remain valid until they expire or are manually revoked.

For more information, see restrict the creation of group and project access tokens.