As part of Atlassian’s ongoing investment in security, we’re excited to introduce token rotation for access tokens in Bitbucket Cloud. Building on recent updates, like adding expiration dates to access tokens, this new capability allows you to rotate your tokens, which generates a new secret while maintaining the same access and scopes.
Why token rotation matters
Access tokens are a secure way to authenticate with Bitbucket Cloud’s APIs, enabling a seamless integration with repositories, workflows, or automation tools like CI/CD systems. Expiration dates provide an essential layer of control by limiting how long a token remains valid, but token rotation enhances this by offering a practical way to refresh a token’s secret and expiration date without needing to recreate it or redefine its scopes.
Here’s why it matters:
- Streamline expiration management: Rotation lets you extend a token’s life with a new secret and expiration date, therefore making it easier to keep credentials active and aligned with your needs.
- Simplify updates: You can refresh a token while keeping its original scopes intact, so updating integrations or workflows is as simple as swapping in the new secret with no reconfiguration required.
- Keep credentials current: Regular rotation helps you proactively maintain fresh tokens, therefore avoiding the hassle of dealing with expired or outdated credentials.
What’s new with token rotation?
You can now rotate any access token whenever you need to. Here’s what happens:
- A brand-new secret is created.
- You can pick a new expiration period that aligns with the maximum allowed by your admin.
- The old token phases out quickly:
- Expired tokens: Rotation generates a fresh, active secret; the old one remains invalid.
- Tokens expiring in <=30 minutes: After rotation, the old token remains usable for any time remaining allowing you to smoothly transition to your newly rotated token.
- Tokens with >30 minutes left: To provide you with a buffer to update your tools but also to ensure the old token expires in a timely manner, the old token’s lifespan is reduced to 30 minutes.
The rotated token carries over its original access and scopes, which keeps your workflows humming along with bolstered security.
How to rotate an access token
Rotating is simple and applies to all token types (repository, project, or workspace):
- Go to Workspace, Project, or Repository settings (depending on where you are creating an access token) > Access tokens which is in the Security section on the left sidebar.
- Locate the token, select … (more options), and select Rotate.
- Choose a new expiration date via the date picker.
- Select Rotate to generate the new token and secret.
- Update your scripts, CI/CD pipelines, or tools with the new secret.
Looking ahead
This feature is part of our broader efforts to strengthen Bitbucket Cloud’s security posture. Stay tuned as we explore enhancements to app passwords and expand controls for other authentication methods.
For more details on access tokens, check out our access token support documentation.