Project access tokens

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.

Create a project access token

To create a project access token:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, 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 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.
7. Select a role for the token.
8. Select one or more project access token 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 cannot view it again.

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

View your access tokens

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.
  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:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, 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.

Rotate a project access token

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.

To rotate a project access token:

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

Revoke a project access token

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.

To revoke a project access token:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Settings > Access tokens.
3. For the relevant token, select Revoke ( ).
4. 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

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

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:

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.

Related topics

• Personal access tokens
• Group access tokens
• Project access tokens API