API token benefits?

[Stojan Cveticanin]

Hi.

I am trying to switch from using app password to api tokens as you marked app password obsolete from 09.09. but I don't see any benefits from it, it just make my life harder.

Your documentation about switching it in SourceTree is not working (it is not possible to use email as username and if I leave username I used with app password it does not work when I switch to api token).

Also, why is necessary for token to have expiration date? That means I should always make alarms once a year to update it everywhere. That does not lead to increased security but to annoying users.

Can you give me some benefits? And can you fix/update documentation how to switch to it in SourceTree?

Greetings,
Stojan

[Ben · Accepted solution]

Hi Stojan,

The primary reason behind switching from App Passwords to API tokens is for security reasons.

The permissions scope for App Passwords is quite limited vs API tokens (which provide more granularity), and the purpose of an expiration is to ensure that older projects which may not be maintained frequently are not able to be compromised by an App Password which does not expire.

Further reasons are highlighted in the announcement post:

• https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation 

Regarding the documentation - this is indeed incorrect. I've created an internal ticket to get this article updated accordingly to avoid further confusion. Thank you for bringing this to our attention.

You'll need to create the API token and make sure that you first specify the correct scope (see: deprecation documentation) - if the scope is incorrect, this could be why it's failing in Sourcetree:

1. Click the gear cog icon, select Atlassian Account settings > Security tab > Create and manage API Tokens

2. Click Create API token with scopes and select Bitbucket Cloud

3. If you want to be able to clone/push/pull to the repository - you'll need to tick both read:repository:bitbucket and write:repository:bitbucket - clone only would just be read:repository:bitbucket.
   More information on scopes can be found in our API scopes documentation.

4. In Sourcetree, you can use either of the following URL formats (if using the first command - you can find your username by clicking the gear cog icon and selecting Personal Bitbucket Settings - it's visible under the Bitbucket Profile Settings heading):
   
   

   https://username:APIToken@bitbucket.org/workspaceID/reposlug.git

https://x-bitbucket-api-token-auth:APIToken@bitbucket.org/workspaceID/reposlug.git

Please perform the above and let me know how this goes. If you are still encountering issues, I will assist you further.

Cheers!

- Ben (Bitbucket Cloud Support)

[Stojan Cveticanin]

Hi Ben,

Thanks for quick answer.

I understand your company's point of view on security, but as I said reasons you said is not benefit for me, I see it just as more job to do. At the end, I don't understand trend to "keep users safe" if the users find this not beneficial but annoying. However, thanks on explanation on this.

About the Sourcetree, I don't understand what you wrote me at all. If I want to create an account it asks for Basic or OAuth authentication, username and password and protocol. It is as simple as that. With my current username and app password it works, if I change app password with api token it does not. My token has all permissions. So, because your change it means I can not use Sourcetree any more starting from June next year.

Greetings,
Stojan

[Ben]

Hi Stojan,

My apologies - I should have clarified. Can you attempt to perform a clone outside of Sourcetree in a terminal window using one of the URL's I provided above? This will allow us to test if the token scope is correct, and if there is an issue with Sourcetree specifically or not:

git clone https://username:APIToken@bitbucket.org/workspaceID/reposlug.git

If the clone succeeds - there may be a problem with the Sourcetree configuration or the platform in general. The authentication type configured should be basic, and the credentials should be your username and APIToken.

Cheers!

- Ben (Bitbucket Cloud Support)

[Stojan Cveticanin]

Hi Ben,

I set up API token instead of app password in my mac key chain and working with git from command line is working fine.

Greetings,
Stojan

[Ben]

Hi @Stojan Cveticanin 

I am also able to use my API Token to clone/push/pull against my GIT repository in a terminal window.

I've attempted to configure API Token in the latest version of Sourcetree for Mac (v4.2.13) and it does not accept the API Token in the configuration settings (requires email, which is not correct) and Basic auth does not authenticate. It seems that this is a platform-specific issue.

I have raised a bug ticket on your behalf accordingly, please Watch this to receive future updates related to it:

• https://jira.atlassian.com/browse/SRCTREE-8218

For now - I'd suggest continuing to use AppPassword, or authenticating your account with OAuth until this is fixed.

Thank you for raising this to our attention.

Cheers!

- Ben (Bitbucket Cloud Support)

[Stojan Cveticanin]

Thanks a lot.

Greetings, 
Stojan

[HidekiShomura]

Hellow, I was also struggling with similar problem.

Similarly, the API token cannot be used as a login in Sourcetree for Windows too, so please fix this in this environment as well.
(I was able to create an API token and authenticate with Sourcetree.)
https://jira.atlassian.com/browse/SRCTREE-8218

[Stojan Cveticanin]

Read the answer I posted bellow, it might help you.

The crucial thing is that your Bitbucket must be of version (at least) 4.2.13 295. Even if you have just a minor one before, you don't have option to choose API token.

[Ben]

Hi @hid3 @Stojan Cveticanin 

I'm still confirming with the Sourcetree team the exact steps needed to both connect to Sourcetree and also clone new/maintain existing GIT repositories with API token.

I've been able to successfully authenticate/clone based on my testing, but I'm waiting for confirmation before posting here and putting a request in to update our documentation.

I did post some steps before - but they did not include troubleshooting connections to existing repositories/performing clones so I removed this post as it was incomplete. I'm happy to hear that these steps were helpful, however :) 

Thank you for your patience.

Cheers!

- Ben (Bitbucket Cloud Support)

[Stojan Cveticanin]

I am copying answer here, to be in this thread.

In Sourcetree, you'll need to perform the following steps:

1. Make sure you're on the latest version of Sourcetree at the time of writing this (v4.2.13 295) by clicking Check for Updates and installing any. This version fully supports API tokens and you may encounter issues with older versions
2. Confirm you're on the latest version by clicking About Sourcetree
3. Once confirmed, access Settings > Accounts tab
4. Click the Add button
5. Select Bitbucket as the host 
6. Select API Token as the Auth Type
7. Enter the user email tied to your Bitbucket Cloud user account
8. Paste your API token from above
9. Click Save

[HidekiShomura]

Yes, I checked my current Sourcetree version and it was version 3.4.24 (the latest version for Windows).
So, on the Sourcetree authentication settings screen, there was a select box for the API token, and I was able to select it and complete the authentication.

However, when I then performed a test fetch using Sourcetree, a popup login form appeared.
I entered my email address as the form ID and my API token as the password, but an error message appeared and I was unable to perform the fetch action.
(As a test, I tried fetching from an existing repository instead of creating a new one.)

This is my current operating situation, so I'll share it with you.

[Ben]

Hi @Stojan Cveticanin @HidekiShomura 

Thank you for your patience. After a long discussion with our Sourcetree development team, they have advised that they will be providing further updates to the software to ensure that the process for adding an API token is more streamlined.

One thing to note - AppPassword is cached with your configured remote URL's. This means it's technically using AppPassword until these remote URL's are removed and re-added (if you check the remote URL in the UI you can verify this):

1. You will need to remove each bookmarked repository in the local tab, and add these again from the remote tab by clicking the Clone button (making sure to use the API token auth for the Source URL):
   https://username:APIToken@bitbucket.org/workspaceID/reposlug.git
2. Once this is done, your local repositories will be updated with the API token for authentication, and this will not need to be undertaken again until the API token expiry date

The minimum required scopes when creating the API token are as follows:

read:user:bitbucket
read:workspace:bitbucket
read:repository:bitbucket
write:repository:bitbucket
read:pullrequest:bitbucket (optional)
write:pullrequest:bitbucket (optional)

Cheers!

- Ben (Bitbucket Cloud Support)

[Stojan Cveticanin]

Answer from Ben, that completes this (I don't know why it is not visible here):

Configuring in Sourcetree:

In Sourcetree, you'll need to perform the following steps:

1. Make sure you're on the latest version of Sourcetree at the time of writing this (v4.2.13 295) by clicking Check for Updates and installing any. This version fully supports API tokens and you may encounter issues with older versions
2. Confirm you're on the latest version by clicking About Sourcetree
3. Once confirmed, access Settings > Accounts tab
4. Click the Add button
5. Select Bitbucket as the host 
6. Select API Token as the Auth Type
7. Enter the user email tied to your Bitbucket Cloud user account
8. Paste your API token from above
9. Click Save