Skip to main content
This covers the current Bitbucket Cloud connector, which authenticates with an Atlassian API token. Make sure you are not connecting Bitbucket (Deprecated), which is no longer supported.

​
After this article

You’ll be able to connect Bitbucket to Lumos to sync users, groups, and project and repository permissions, and to provision user project and repository permissions.

​
Capabilities

​
Required plan and roles

  • Atlassian account: create the API token from an account with administrative access to the workspace, so the admin-level scopes below can be granted.
  • API token scopes (full functionality, sync plus provisioning):
  • Scopes for full functionality (generic form): Account read and write. Workspace membership read and write. Projects read, write, admin. Repositories read, write, admin, delete.
  • Read-only option: to connect read-only (sync without provisioning), grant every scope except write:permission:bitbucket-token and delete:permission:bitbucket-token. That means read:user, read:workspace, admin:workspace, read:project, admin:project, read:repository, and admin:repository. The three admin: scopes read group memberships and permission grants, they don’t write them. A token with only the plain read: scopes fails the group and association sync, see Read-only access vs provisioning below.

​
Read-only access vs provisioning

Is read-only possible? Yes, but not with the plain read scopes alone. Create the Atlassian API token with every scope except write:permission:bitbucket-token and delete:permission:bitbucket-token. Those two are the only write actions. The admin:workspace, admin:project, and admin:repository scopes read group and permission data, so they’re required for a complete sync even though Lumos never writes with them. What read-only requires. An Atlassian API token scoped to read:user:bitbucket-token, read:workspace:bitbucket-token, admin:workspace:bitbucket-token, read:project:bitbucket-token, admin:project:bitbucket-token, read:repository:bitbucket-token, and admin:repository:bitbucket-token, created from an account with administrative access to the workspace. Bitbucket bundles reading group memberships and permission grants under the admin: scopes, so they’re needed for sync. Omit only write:permission:bitbucket-token and delete:permission:bitbucket-token. What full provisioning requires. The same token with the two write scopes added on top of the read-only set: write:permission:bitbucket-token and delete:permission:bitbucket-token, so Lumos can grant and remove permissions instead of only reading them. Watch out for. A missing scope fails the sync. So a read-only token missing the admin: scopes doesn’t just hide groups, it fails those sync stages. If provisioning actions fail while sync keeps working, the token is missing write:permission and delete:permission, recreate it with those added.

​
Instructions

Phase 1: Create an API token in Bitbucket
  1. Go to your Atlassian account’s API tokens page (id.atlassian.com > Security > API tokens) and create an API token with scopes, selecting Bitbucket and the scopes listed above.
  2. Copy and save the token. It is only shown once.
  3. Note your Account E-mail: the Atlassian account email listed under Bitbucket profile settings on your Personal settings page.
  4. Note your Workspace ID: the value immediately following https://bitbucket.org/ in any repository or workspace URL. In https://bitbucket.org/<your-workspace-id>/<repository-name>, enter just <your-workspace-id>.
Phase 2: Connect in Lumos
  1. Find the Bitbucket card in your Lumos integrations (reconnect an existing card or add a new one).
  2. Enter the Account E-mail, API Token, and Workspace ID.
  3. Click Connect.

​
API Endpoints Used

​
Troubleshooting

Connection fails immediately. Verify you connected the current Bitbucket card, not Bitbucket (Deprecated). Confirm the Account E-mail matches the Atlassian account that created the API token, and the Workspace ID is the URL slug (not the display name). Groups or group permissions missing. Group data is read via Bitbucket’s legacy 1.0 groups API and requires the admin:workspace:bitbucket-token scope. Recreate the token with all admin scopes if groups don’t appear. Provisioning actions fail but sync works. The token was likely created with read-only scopes. Recreate it including the admin:project, admin:repository, write:permission, and delete:permission scopes. Token expired. Atlassian API tokens are created with an expiration date. If syncs stop with authentication errors, create a new token and reconnect.