API Token Scopes for Bitbucket

[Neil Walsh]

When creating a Bitbucket API Token for use with Sourcetree, what specific scopes are required for the full functionality of the app.

I keep guessing and finding that I'm missing another scope (latest was create remote repo from local). I need to write some documentation for all our users to migrate from app passwords to api tokens and I'm reluctant to just say select "select all scopes" as this feels overly permissive.

Does anyone have an authoritative list?

Thanks!

Neil

[jhocking]

Sourcetree wouldn't authenticate my API token for a while, but eventually it authenticated with the following:

• admin:repository:bitbucket
• read:account
• read:repository:bitbucket
• read:user:bitbucket
• write:repository:bitbucket

I could maybe pare down that list even more (I stopped trying after this success) but this is the smallest list that worked for me.

I do agree though that this needs to be documented. I was flabbergasted that the error in the app only says I need more privileges without specifying what was missing!

[Tomislav Tobijas]

@Neil Walsh any chance you've figured this out? It would be cool to see the full/final list if you've managed to find all the permissions you need to get this to work 👀

I've been playing with Service accounts on cloud, and when I saw there are almost 500 scopes/options to select, it was quite interesting to find those that we needed for one integration 🫠

Anyway, I see we'll have to work on that and potentially create some kind of 'lists' or cheat sheets for future reference, so any insights would be great 😅

[Tomislav Tobijas]

Hi @Neil Walsh ,

I guess the minimum would be something like (note: needs to be checked/tested):

• read:account
• read:me
• read:pullrequests:bitbucket
• read:repository:bitbucket
• read:workspace:bitbucket
• write:repository:bitbucket
• write:pullrequests:bitbucket
• admin:repository:bitbucket

Basically, scope type = Classic, and you can filter out scope actions for read and write. 

Again, it would depend on your requirements, but these are, I'd say, standard ones 👀

Note that I've always just selected all of them, but I'm mainly testing something, so that info might not be that relevant.

Cheers,
Tobi

[Neil Walsh]

Thanks Tomislav. I guess you maybe don't use bitbucket pipelines?

This was my issue really. I'm trying to understand what I need to use the full feature set of Sourcetree.

I'm at this at the moment (which seems to work) but I'm sure there's a couple in there I don't need and I wonder if I've missed some. 

Admin

• admin:workspace:bitbucket
• admin:repository:bitbucket
• admin:project:bitbucket
• admin:pipeline:bitbucket

Read

• read:workspace:bitbucket
• read:user:bitbucket
• read:runner:bitbucket
• read:repository:bitbucket
• read:project:bitbucket
• read:package:bitbucket
• read:permission:bitbucket
• read:pipeline:bitbucket

Write

• write:user:bitbucket
• write:repository:bitbucket

[Tomislav Tobijas]

Yeah, I didn't use pipelines, so that's why they are missing. 

If you've got Rovo (so basically any paid cloud subscription), it will most likely give you a correct list based on your requirements. It did a really good job for me in a couple of similar situations. Or, Claude will also provide decent replies if you give it the full list of permissions (all that exist) and give it a context of what you actually use within your team/org.

I mean, permissions/scopes are relatively intuitive based on their labels, but in the end, it comes to performing a couple of tests just to be clear if everything is working as expected.

Potentially, someone will chime in here if they use this kind of authorization extensively, but again, pretty much any AI should give you a decent enough list that's like MVP based on your scenario and usage. 👀