> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumos.com/llms.txt > Use this file to discover all available pages before exploring further. # Bitbucket *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 | Functionality | Type | Sync | Provision | Description | | :- | :- | :- | :- | :- | | Users | Account | Yes | No | User accounts | | User Project Permissions | Permission | Yes | Yes | Per-user project permissions | | User Repo Permissions | Permission | Yes | Yes | Per-user repository permissions | | Group Project Permissions | Permission | Yes | No | Group project permissions | | Group Repo Permissions | Permission | Yes | No | Group repository permissions | ## 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):** | Scope | Purpose | | :- | :- | | `read:user:bitbucket-token` | Read user information | | `read:workspace:bitbucket-token` | Read workspace details and members | | `admin:workspace:bitbucket-token` | Read workspace user groups and group memberships | | `read:project:bitbucket-token` | Read project information | | `admin:project:bitbucket-token` | Read and manage project permissions | | `read:repository:bitbucket-token` | Read repository information | | `admin:repository:bitbucket-token` | Read and manage repository permissions | | `write:permission:bitbucket-token` | Grant or update user permissions | | `delete:permission:bitbucket-token` | Remove user permissions | * **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//`, enter just ``. **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 The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them. ## 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.