doc/user/group/settings/group_access_tokens.md
{{< details >}}
{{< /details >}}
Group access tokens provide authenticated access to a group and its projects. They are similar to personal access tokens and project access tokens, but are attached to a group rather than a user or project. You cannot use group access tokens to create other group, project, or personal access tokens.
You can use a group access token to authenticate:
Prerequisites:
[!note] On GitLab.com, group access tokens require a Premium or Ultimate subscription. They are not available during a trial.
On GitLab Self-Managed and GitLab Dedicated, group access tokens are available with any license.
{{< 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 group access token:
A group access token is displayed. Save the group access token somewhere safe. After you leave or refresh the page, you cannot view it again.
All group access tokens inherit the default prefix setting configured for personal access tokens.
[!warning] Group access tokens are treated as internal users. If an internal user creates a group access token, that token can access all projects that have visibility level set to Internal.
If you are an administrator, you can create group access tokens in the Rails console:
Run the following commands in a Rails console:
# Set the GitLab administration user to use. If user ID 1 is not available or is not an administrator, use 'admin = User.admins.first' instead to select an administrator.
admin = User.find(1)
# Set the group you want to create a token for. For example, group with ID 109.
group = Group.find(109)
# Create the group bot user. For further group access tokens, the username should be `group_{group_id}_bot_{random_string}` and email address `group_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}`.
random_string = SecureRandom.hex(16)
service_response = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot_#{random_string}", email: "group_#{group.id}_bot_#{random_string}@noreply.#{Gitlab.config.gitlab.host}", user_type: :project_bot }).execute
bot = service_response.payload[:user] if service_response.success?
# Confirm the group bot.
bot.confirm
# Add the bot to the group with the required role.
group.add_member(bot, :maintainer)
# Give the bot a personal access token.
token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token')
# Get the token value.
gtoken = token.token
Test if the generated group access token works:
Use the group access token in the PRIVATE-TOKEN header with GitLab REST APIs. For example:
Use the group token to clone a group's project using HTTPS.
{{< history >}}
pat_ip. Enabled by default in 17.9.pat_ip removed.{{< /history >}}
The group 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 group access tokens:
Active and usable access tokens are stored in the Active group access tokens section. Expired, rotated, or revoked tokens are stored in the Inactive group access tokens section.
{{< history >}}
retain_resource_access_token_user_after_revoke. Disabled by default.retain_resource_access_token_user_after_revoke removed.{{< /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. 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 group access token:
{{< history >}}
retain_resource_access_token_user_after_revoke. Disabled by default.retain_resource_access_token_user_after_revoke removed.{{< /history >}}
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 group 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.pat_expiry_inherited_members_notification. Disabled by default.pat_expiry_inherited_members_notification enabled by default in GitLab 17.10.pat_expiry_inherited_members_notification removed in GitLab 17.11{{< /history >}}
GitLab runs a daily check at 1:00 AM UTC to identify group access tokens that expire soon. Direct members with the 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, inherited members with the Owner role can also receive these emails. You can configure this for every group on the GitLab instance or a specific group. If applied to a parent group, this setting is inherited by all descendant groups and projects.
Expired tokens appear in the inactive group access tokens section until they're automatically deleted. On GitLab Self-Managed, you can modify this retention period.
When you create a group access token, GitLab creates a bot user and associates it with the token.
Bot users have the following properties:
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: group_{group_id}_bot_{random_string} | group_123_bot_4ffca233d8298ea1 |
Generated in this format: group_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host} | [email protected] |
To limit potential abuse, you can restrict users from creating access tokens in a top-level group and any descendant subgroups or projects. Any existing tokens remain valid until they expire or are manually revoked.
To restrict the creation of access tokens: