Use OAuth on Bitbucket Cloud

Bitbucket Cloud REST API integrations, and Atlassian Connect for Bitbucket add-ons, can use OAuth 2.0 to access resources in Bitbucket.

OAuth 2.0

For obtaining access/bearer tokens, we support three of RFC-6749's grant flows, plus a custom Bitbucket flow for exchanging JWT tokens for access tokens. Note that Resource Owner Password Credentials Grant (4.3) is no longer supported. Check out our OAuth 2.0 developer documentation for more details.

This section provides the basic OAuth 2.0 information to register your consumer and set up OAuth 2.0 to make API calls.

Create a consumer

OAuth needs a key and secret, together these are know as an OAuth consumer. You can create a consumer on any existing workspace. To create a consumer, do the following:

Select your avatar (Your profile) from the navigation bar at the top of the screen.
Under Recent workspaces, select the workspace that will be accessed using the consumer; or find and open the workspace under All workspaces.
Select the Settings cog on the top navigation bar.
Select Workspace settings from the Settings dropdown menu.
On the sidebar, under Apps and features, select OAuth consumers.
Click the Add consumer button.
The system requests the following information:
Name: The display name for your consumer. This must be unique within your account. This is required.
Description: An optional description of what your consumer does.
Callback URL: Required for OAuth 2.0 consumers.
When making requests you can include a call back URL in the request:
- If you do include the URL in a request it must be appended to the same URL configured in the consumer. So if your consumer callback URL is example.com/add-on the URL in your request must be something similar to example.com/add-on/function.
- If you don't include the URL in the request we redirect to the callback URL in the consumer.
URL: An optional URL where the curious can go to learn more about your cool application.
Click Save. The system generates a key and a secret for you.
Toggle the consumer name to see the generated Key and Secret value for your consumer.

Access tokens

For obtaining access/bearer tokens, we support three of RFC-6749's grant flows, plus a custom Bitbucket flow for exchanging JWT tokens for access tokens through the following URL's:

https://bitbucket.org/site/oauth2/authorize

https://bitbucket.org/site/oauth2/access_token

Resource Owner Password Credentials Grant (4.3) is no longer supported. Check out our OAuth 2.0 developer documentation for more details.

Grant types

Authorization code grant

The full-blown 3-LO flow. Request authorization from the end user by sending their browser to:

https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=code

The callback includes the ?code={} query parameter that you can swap for an access token:

$ curl -X POST -u "client_id:secret" \
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=authorization_code -d code={code}

Implicit grant

Useful for browser-based operations without data center-side back end support. This grant type requests authorization from the user by directing their browser to:

https://bitbucket.org/site/oauth2/authorize?client_id={key}&response_type=token

That will redirect to the callback URL with a fragment containing the access token (#access_token={token}&token_type=bearer) where your page's JavaScript can pull it out of the URL.

Making requests

Once you have an access token, as per RFC-6750, you can use it in a request in any of the following ways (listed from most to least desirable):

Send it in a request header: Authorization: Bearer {access_token}
Include it in a (application/x-www-form-urlencoded) POST body as access_token={access_token}
Put in the query string of a non-POST: ?access_token={access_token}

Refresh tokens

Our access tokens expire in two hours. When this happens you'll get 401 responses.

Most access token grant response therefore include a refresh token that can then be used to generate a new access token, without the need for end user participation:

$ curl -X POST -u "client_id:secret"
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=refresh_token -d refresh_token={refresh_token}

Scopes

Scopes are defined on the client/consumer instance. Bitbucket Cloud does not currently support the use of the optional scope parameter on the individual grant requests.

When the scope parameter is provided, Bitbucket will validate that it contains no scopes that were not already present on the client/consumer and fail if additional scopes are requested, but asking for fewer scopes will not affect the resulting access token.

For a list of available scopes and details of the access they grant, visit Atlassian Developer: Bitbucket Cloud Reference — Scopes.

Cloning a repository with an access token

Since add-ons will not be able to upload their own SSH keys to clone with, access tokens can be used as Basic HTTP Auth credentials to clone securely over HTTPS.

$ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.git

The literal string x-token-auth as a substitute for username is required.

Our process is similar to GitHub, yet slightly different: the difference is GitHub puts the actual token in the username field.

Delete a consumer

Select Settings (theicon) on the top navigation bar.
Select Workspace settings under the Bitbucket Administration heading in the Settings dropdown menu.
Select Oauth consumers under Apps and features on the left sidebar.
Select on the right side of the consumer entry you want to delete.
Select Delete. This also removes all existing tokens linked to that consumer.

If you need to delete a consumer because its credential has been compromised, follow the procedure outlined in App security incident management guidelines for Marketplace Partners.

OAuth consumer examples
See some examples of how consumers are using OAuth libraries.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community