Imagine this: You are an engineer at a growing tech company, and it’s 2 a.m. when you get an urgent call. A critical deployment pipeline has failed, and your team is scrambling to figure out why. After hours of digging, you realize someone revoked a personal access token belonging to an engineer who left the company a week ago. This token was tied to several key automation processes, and now your entire system is in chaos. How do you make sure it does not happen again?Follow this guide, which takes GitLab customers through the end-to-end process of identifying, managing, and securing their tokens. It is meant to be a handy supplement to the extensive token overview documentation for GitLab administrators, developers, and security teams who need to ensure proper token management within their projects.Here's what is covered in this guide:How to select the right token for the jobToken typesDiscovering your tokensCredentials inventoryManaging tokens in the GitLab UI and APIToken rotation and expiration managementToken management best practicesService accountsHow to select the right token for the jobChoosing the right token ensures optimal security and functionality based on your use case.Tokens can be used for authenticating API requests, automating CI/CD pipelines, integrating third-party tools, managing deployments and repositories, and more.For the sake of simplicity, the chart illustrates a straightforward use case tied to single user ownership. For more information, check out our documentation of user roles and permissions at each namespace (user/group) in your instance or top-level group. Example use cases could be as follows:Personal access tokens (PAT) can be used by developers when a user's personal access and permissions are required. In this case, the credentials follow the status and permissions of the user, including the removal of access if the account loses access to a specific project or group (or is blocked entirely).Project/group access tokens (PrAT/GrAT) are recommended when access should be scoped to resources within a specific project/group, allowing anyone with a PrAT/GrAT to access those resources through mechanisms managed by assigned scopes.Token typesBelow is a list of GitLab tokens with their default prefixes and use cases. For more information, please visit the GitLab Token overview page.TokensPrefixDescriptionPersonal access tokenglpatAccess user-specific dataOAuth 2.0 TokengloasIntegrate with third-party applications using OAuth2.0 authentication protocolImpersonation tokenglpatAct on behalf of another user for administrative purposesProject access tokenglpatAccess data from a specific projectGroup access tokenglpatAccess data from a specific groupDeploy tokengldtClone, push, and pull container registry images of a project without a user and a passwordDeploy keysN/AAllow read-only or read-write access to your repositoriesRunner authentication tokenglrtAuthenticate GitLab RunnersCI/CD job tokenglcbtAutomate CI/CD processesTrigger tokenglpttTrigger pipelines manually or programmaticallyFeed tokenglftAuthenticate access to package/RSS feedsIncoming mail tokenglimtProcess incoming emailsGitLab agent for Kubernetes tokenglagentManage Kubernetes clusters via the GitLab agentSCIM tokensglsoatEnable SCIM integrations for user provisioningFeature flags client tokenglffctEnable feature flags programmaticallyWebhook tokenN/AUser set secret token to secure webhook payloads and ensure that the requests are from GitLabDiscovering your tokensCredentials inventoryOn GitLab Ultimate, administrators (GitLab Self-Managed) and top-level group owners of an enterprise organization (GitLab.com as of Version 17.5) can monitor the credentials in their namespace.This inventory tracks token details such as:Token typeAvailable tokens on GitLab.comAvailable tokens on GitLab Self-ManagedAssociated user accountsToken scopes, and creation and expiration datesToken last used IP addresses (as of GitLab 17.10)Token filtration based on the above user-defined parametersAbility to revoke and rotate those tokensA well-maintained credentials inventory helps identify over-permissioned tokens, and gives insight into credentials that may need to be rotated, ensuring a secure and efficient workflow. Credentials inventory APIAs a complement to the UI, there is ongoing development to release a credentials inventory API through the new /group/:id/manage endpoint. The credentials accessible under this endpoint are limited to enterprise users, and can be accessed by the top-level group owner of an enterprise organization. An example of the future API call would be:curl --header "PRIVATE-TOKEN: " "https://verified_domain.com/api/v4/groups//manage/personal_access_tokens" GitLab APIThe GitLab API allows you to programmatically list and manage tokens within your organization. Key authentication-related endpoints support various token types), including personal, group, CI/CD tokens, and more. An example of using a personal access token to list all visible projects across GitLab for the authenticated user is:curl --header "PRIVATE-TOKEN: " \ "https://gitlab.example.com/api/v4/projects"Watch this video to learn how to make API calls to the GitLab API. Finding where tokens are usedCustomers can find where tokens are used in different ways:under User Profile > Access Tokensin credentials inventoryin audit eventsvia the APIInformation on token usage is updated every 10 minutes for last_used and every minute for last_used_ip.The ability to view IP addresses was introduced in GitLab 17.9, and is controlled by the :pat_ip feature flag. Follow these steps to view the last time a token was used, along with its last five distinct IP addresses.Managing tokens in the GitLab UI and APIThe following table includes videos detailing a few token creations in the UI and demonstrates their usage via the API.TokensGitLab UIGitLab APIPersonal access tokenDocumentation and videoDocumentation and videoGroup access tokenDocumentation and videoDocumentation and videoProject access tokenDocumentation and videoDocumentation and videoToken rotation and expiration managementImplementing token rotation and strict expiration policies reduces the risk of compromise and ensures compliance with security standards. Regular rotation and enforced expirations prevent stale credentials from becoming security vulnerabilities.Previously, expired group and project access tokens were automatically deleted upon expiration, which made auditing and security reviews more challenging due to the lack of a record of inactive tokens. To address this, a recent feature introduced the retention of inactive group and project access token records in the UI for 30 days after they became inactive. This enhancement aims to allow teams to track token usage, expiration, and revocation for better compliance and monitoring.To be more proactive in your token rotation and expiration management, do the following:Actively rotate your tokens via the UI or API. If you use the latter, be mindful of the automatic token reuse detection security mechanism.Set an instance-wide maximum lifetime limit for access tokens.Token rotation APIUntil GitLab 17.7, customers had to programmatically rotate access tokens with the API. Its counterpart is now available on the UI. Check out the video in the table below or follow the documentation for guidance.Token rotation snippetsThe following table includes videos detailing the rotation of GitLab tokens.TokensPrerequisitesGitLab UIGitLab APIPersonal access tokenScope: apiDocumentation and videoDocumentation and videoGroup access tokenScope: api and Role(s): ownerDocumentation and videoDocumentation and videoProject access tokenScope: api and Role(s): owner, maintainerDocumentation and videoDocumentation and videoToken management best practicesPrinciple of least privilegeMitigate risk by restricting assigned permissions to tokens required for their respective tasks. This allows you to proactively predict and troubleshoot points of failure in your systems. You can do this by:Selecting the right token for the right job. See the flowchart.Assign only the required scopes when creating a token. For example, use read-only scopes for tokens with auditor-like jobs. See roles.Avoid granting administrative privileges unless specifically required.Enforce instance-wide default token lifetimes.Regularly review and audit token permissions to ensure they align with current operational needs.Revoke tokens once the task is complete.Service accountsService accounts ensure tokens are tied to non-human entities, separating them from individual user accounts and reducing dependency on specific users. Instead of using personal accounts to generate tokens for automation, create service accounts with limited scopes. Benefits include:Usage of service account tokens in CI/CD pipelines to avoid disruptions caused by user account changesProgrammatically automate rotation processes, as personal accounts remain unaffectedClearer monitoring and auditing trail of actions taken by service accountsService accounts with no expiration dateDoes not consume a license seatGitLab plans to release a new Service Accounts UI as a counterpart to its API-based creation, designed to simplify the management of service accounts and their associated tokens. Check out the demo below on the programmatic usage of service accounts. Vulnerability toolsLeverage GitLab’s built-in security tools to identify and mitigate vulnerabilities associated with token usage. For maximum coverage, it is recommended to use them all in tandem.Secret Detection: Scans your repository for hardcoded secrets like API tokens, passwords, and other sensitive information. View the list of detected secrets.Static Application Security Testing (SAST): Analyzes your source code for security vulnerabilities and provides reports with UI findings in merge requests, among other features.Dependency Scanning: Ensures that third-party libraries used in your project do not expose token-related vulnerabilities.Audit logs and monitoringMaintain token health by regularly reviewing audit logs and token usage, instance- and/or group-wide.Audit events: Enable audit event logging in GitLab to track token-related activities such as creation, usage, deletion and unusual API calls (unpermitted parameters in logs, and consistent triggers of the rate limiter).IP allowlisting: Helps prevent malicious users from hiding their activities behind multiple IP addresses.Alerts: Set up alerts for unusual activities (trigger paging for on-call rotations or be used to create incidents).Credentials inventory: Complete control of all available access tokens with the ability to revoke as needed.Notifications: Proactively handle any token (group, project, and personal) expiration notification emails you receive. Based on customer demand, this feature was recently extended to include 30-day and 60-day notifications from the seven-day default.Webhooks: Access token webhooks can be configured on groups and projects to send seven-day token expiry events. This feature was also recently extended to include 30-day and 60-day notifications behind the :extended_expiry_webhook_execution_setting feature flag (disabled by default).What's nextWith GitLab’s large token catalog, there are ongoing plans for consolidation with a focus on the lifetime, fine-grained scopes, consistent management, and usage. Our current prioritized token-related features include a complete UI for service accounts, additional credential types in the credentials inventory, and improved auditing for tokens and service accounts.Sign up for a free 60-day trial of GitLab Ultimate to start using token management.