# Bitbucket access tokens (/integrations/bitbucket-service-account)

Connect Bitbucket Cloud with an access token when a workflow should act as an integration rather than as the person who connected it. An access token belongs to a workspace, project, or repository, not to a user, so it keeps working when people leave and its reach is limited to what it was created for.

Bitbucket shows actions taken with the token (comments, merges, pipeline runs) under the token's name.

## Prerequisites \[#prerequisites]

Admin access to the workspace, project, or repository the token is for. Workspace and project access tokens require a Bitbucket Cloud Premium plan; repository access tokens do not.

## Create the access token \[#creating-the-access-token]

Open the repository, project, or workspace settings in Bitbucket Cloud and go to **Access tokens**

Click **Create access token** and give it a name (e.g. `Sim workflows`) — this is the name Bitbucket shows on everything the workflow does

Select **Repositories: Read** (`repository`). Add **Pull requests**, **Repositories: Write**, or **Pipelines** scopes for the actions the workflow takes

Create the token and copy it right away — Bitbucket shows it only once

Warning:

A repository access token can only reach its repository, and a project access token only the repositories in its project. Treat the token like a password; Sim encrypts it at rest.

## Add the access token to Sim \[#adding-the-access-token-to-sim]

Open **Integrations** from your workspace sidebar

Search for "Bitbucket" and open it, then click **Add to Sim** and choose **Add access token**

Paste the token and enter a repository it can read as `workspace/repository` (the `my-workspace/my-repository` in `bitbucket.org/my-workspace/my-repository`). For a repository access token, that is its own repository

Click **Add access token**. Sim verifies the token by reading that repository once, so the token needs the `repository` scope

## Use the credential in workflows \[#using-the-credential-in-workflows]

Add a Bitbucket block and select the saved access token in the account dropdown, then choose the workspace and repository. The block calls `api.bitbucket.org` with the token, exactly as it does with a connected account.

Two things need a signed-in account and do not work with an access token:

- **List Workspaces** lists the workspaces of the person who connected the account, so Sim refuses to run it with an access token. Use a connected account for it.
- The workspace picker lists a person's workspaces, so it cannot load them for an access token. Switch the workspace field to manual entry and type the slug.

## Rotate tokens and handle permission failures \[#rotate-tokens-and-handle-permission-failures]

If validation succeeds but an action fails, the token is likely missing that action's scope, or the repository is outside the token's project or repository. Access tokens cannot be edited after creation: create a replacement with the right scopes, update the credential in Sim, test the workflow, and then revoke the old token. See [Bitbucket's access token documentation](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/).