Project access tokens

Project access tokens are similar to passwords, except you can limit access to resources, select a limited role, and provide an expiry date.

Use a project access token to authenticate:

• With the GitLab API.
• With Git, when using HTTP Basic Authentication, use:
  • Any non-blank value as a username.
  • The project access token as the password.

Project access tokens are similar to group access tokens and personal access tokens, but project access tokens are scoped to a project, so you cannot use them to access resources from other projects.

On GitLab Self-Managed instances, project access tokens are subject to the same maximum lifetime limits as personal access tokens if the limit is set.

You can use project access tokens:

• On GitLab SaaS: If you have the Premium or Ultimate license tier, only one project access token is available with a trial license.
• On GitLab Self-Managed instances: With any license tier. If you have the Free tier, consider restricting the creation of project access tokens to lower potential abuse.

You cannot use project access tokens to create other group, project, or personal access tokens.

Project access tokens inherit the default prefix setting configured for personal access tokens.

Create a project access token

To create a project access token:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Access tokens.
3. Select Add new token.
4. In Token name, enter a name. The token name is visible to any user with permissions to view the project.
5. Optional. In Token description, enter a description for the token.
6. In Expiration date, enter an expiry date for the token.
   • The token expires on that date at midnight UTC. A token with the expiration date of 2024-01-01 expires at 00:00:00 UTC on 2024-01-01.
   • If you do not enter an expiry date, the expiry date is automatically set to 30 days later than the current date.
   • By default, this date can be a maximum of 365 days later than the current date. In GitLab 17.6 or later, you can extend this limit to 400 days.
   • An instance-wide maximum lifetime setting can limit the maximum allowable lifetime in GitLab Self-Managed instances.
7. Select a role for the token.
8. Select the desired scopes.
9. 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 can’t view it again.

Revoke or rotate a project access token

In GitLab 17.9 and later, you can view both active and inactive project access tokens on the access tokens page.

The inactive project access tokens table displays revoked and expired tokens for 30 days after they became inactive.

Tokens that belong to an active token family are displayed for 30 days after the latest active token from the family is expired or revoked.

To revoke or rotate a project access token:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Access tokens.
3. For the relevant token, select Revoke ( ) or Rotate ( ).
4. On the confirmation dialog, select Revoke or Rotate.

Scopes for a project access token

The scope determines the actions you can perform when you authenticate with a project access token.

Restrict the creation of project access tokens

To limit potential abuse, you can restrict users from creating tokens for a group hierarchy. This setting is only configurable for a top-level group and applies to every downstream project and subgroup. Any existing project access tokens remain valid until their expiration date or until manually revoked.

1. On the left sidebar, select Search or go to and find your group. This group must be at the top level.
2. Select Settings > General.
3. Expand Permissions and group features.
4. In Permissions, clear the Users can create project access tokens and group access tokens in this group checkbox.

Access token expiration

Whether your existing project access tokens have expiry dates automatically applied depends on what GitLab offering you have, and when you upgraded to GitLab 16.0 or later:

• On GitLab.com, during the 16.0 milestone, existing project access tokens without an expiry date were automatically given an expiry date of 365 days later than the current date.
• On GitLab Self-Managed, if you upgraded from GitLab 15.11 or earlier to GitLab 16.0 or later:
  • On or before July 23, 2024, existing project access tokens without an expiry date were automatically given an expiry date of 365 days later than the current date. This change is a breaking change.
  • On or after July 24, 2024, existing project access tokens without an expiry date did not have an expiry date set.

On GitLab Self-Managed, if you do a new install of one of the following GitLab versions, your existing project access tokens do not have expiry dates automatically applied:

• 16.0.9
• 16.1.7
• 16.2.10
• 16.3.8
• 16.4.6
• 16.5.9
• 16.6.9
• 16.7.9
• 16.8.9
• 16.9.10
• 16.10.9
• 16.11.7
• 17.0.5
• 17.1.3
• 17.2.1

Project access token expiry emails

GitLab runs a check every day at 1:00 AM UTC to identify project access tokens that are expiring in the near future. Members of the project with at least the Maintainer role are notified by email when these tokens expire in a certain number of days. The number of days differs depending on the version of GitLab:

• In GitLab 17.6 and later, project maintainers and owners are notified by email when the check identifies their project access tokens as expiring in the next sixty days. An additional email is sent when the check identifies their project access tokens as expiring in the next thirty days.
• Project maintainers and owners are notified by email when the check identifies their project access tokens as expiring in the next seven days.
• In GitLab 17.7 and later, project members who have inherited the Owner or Maintainer role due to the project belonging to a group can also receive notification emails. You can enable this by changing:
  • The group setting in any of the parent groups of the project.
  • On GitLab Self-Managed, the instance setting.

Your expired access tokens are listed in the inactive project access tokens table for 30 days after the tokens expire.

Bot users for projects

Bot users for projects are GitLab-created non-billable users. Each time you create a project access token, a bot user is created and added to the project. This user is not a billable user, so it does not count toward the license limit.

The bot users for projects have permissions that correspond with the selected role and scope of the project access token.

• The name is set to the name of the token.
• The username is set to project_{project_id}_bot_{random_string}. For example, project_123_bot_4ffca233d8298ea1.
• The email is set to project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}. For example, project_123_bot_4ffca233d8298ea1@noreply.example.com.

API calls made with a project access token are associated with the corresponding bot user.

Bot users for projects:

• Are included in a project’s member list but cannot be modified.
• Cannot be added to any other project.
• Can have a maximum role of Owner for a project. For more information, see Create a project access token.

When the project access token is revoked:

• The bot user is retained for 30 days.
• After 30 days the bot user is deleted. All records are moved to a system-wide user with the username Ghost User.

See also Bot users for groups.

Token availability

More than one project access token is only available in paid subscriptions. In Premium and Ultimate trial subscriptions, only one project access token is included. For more information, see the “What is included” section of the GitLab Trial FAQ.

Related topics

• Project access tokens API