OAuth on Bitbucket Cloud

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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

Our OAuth 2 implementation supports all 4 of RFC-6749's grant flows.

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 individual or team account. To create a consumer, do the following:

  1. From your avatar in the bottom left, click Bitbucket settings.
  2. Click OAuth from the left navigation.
    Click the Add consumer button.  
    The system requests the following information:

    Field Description
    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.
  3. Click Save
    The system generates a key and a secret for you.
  4. Toggle the consumer name to see the generated Key and Secret value for your consumer.

Access tokens

We support all 4 of RFC-6749's grant flows to obtain access tokens through the following URL's:


Grant types

Authorization code grant

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


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 server-side back end support. This grant type requests authorization from the user by directing their browser to:


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):

  1. Send it in a request header: Authorization: Bearer {access_token}
  2. Include it in a (application/x-www-form-urlencoded) POST body as access_token={access_token}
  3. 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 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.

The following scopes are available:

Scope name Description

Grants read-only access to all the user's account information.

  • see all email addresses
  • language
  • location
  • website
  • full name
  • SSH keys
  • user groups

Grants the ability to change properties on the user's account.

  • delete the authorizing user's account
  • manage the user's groups
  • manipulate a user's email addresses
  • change username, display name and avatar

Grants the ability to get a list of teams of which the current user is a member. This is covered by the teams endpoint.

  • information about all the groups and teams I am a member or admin of

Grants (implies) the team scope and adds the ability to manage the teams on which the authorizing user is an administrator.

  • manage team permissions

Grants read access to all the repositories to which the authorizing user has access. Note that this scope does not give access to a repository's pull requests.

  • access to the repo's source code
  • clone over https://
  • access the file browsing API
  • download zip archives of the repo's contents
  • the ability to view and use the issue tracker on any repo (created issues, comment, vote, etc)
  • the ability to view and use the wiki on any repo (create/edit pages)

Grants (implies) the repository scope and adds write access to all the repositories to which the authorizing user has access. No distinction is made between public or private repos. This scope alone does not give access to the pull requests API.

  • push access over https
  • fork repos

Grants admin access to all the repositories to which the authorizing user has access. No distinction is made between public or private repos. This scope does not imply repository or repository:write. It gives access to the admin features of a repo only, not direct access to its contents. Of course it can be (mis)used to grant read access to another user account who can then clone the repo, but repos that need to read or write source code would also request explicit read or write. This scope comes with access to the following functionality:

  • view and manipulate committer mappings
  • list and edit deploy keys
  • ability to delete the repo
  • view and edit repo permissions
  • view and edit branch permissions
  • import and export the issue tracker
  • enable and disable the issue tracker
  • list and edit issue tracker version, milestones and components
  • enable and disable the wiki
  • list and edit default reviewers
  • list and edit repo links (Jira/Bamboo/Custom)
  • list and edit the repository web hooks
  • initiate a repo ownership transfer

Grants read access to pull requests and the ability to collaborate on a specific pull request through comments, tasks, and approvals. This scope implies repository, giving read access to the pull request's destination repository.

  • see and list pull requests
  • create and resolve tasks

Grants (implies) the  pullrequest scope and adds the ability to create, merge and decline pull requests. This scope also implies repository:write, giving write access to the pull request's destination repository. This is necessary to facilitate merging.

  • merge pull requests
  • decline pull requests
  • create pull requests
  • comment on pull requests
  • approve pull requests

Grants read access to all the snippets to which the authorizing user has access. No distinction is made between public and private snippets (public snippets are accessible without any form of authentication).

  • view any snippet
  • create snippet comments

Grants write access to all the snippets the authorizing user can edit. No distinction is made between public and private snippets (public snippets are accessible without any form of authentication). This implies the Snippet Read scope which does not need to be requested separately.

  • edit snippets
  • delete snippets

Grants the ability to interact with an issue tracker as if you had no other repository access. This scope does not imply any other scopes and does not give implicit access to the repository the issue is attached to.

  • view, list and search issues
  • create new issues
  • comment on issues
  • watch issues
  • vote for issues

Grants (implies) the issue scope and adds the ability to transition and delete issues. This scope does not imply any other scopes and does not give implicit access to the repository to which the issue is attached.

  • transition issues
  • delete issues


Grants access to wikis. No distinction is made between read and write as wikis are always editable by anyone. This scope does not imply any other scopes and does not give implicit access to the repository the wiki is attached to.

  • view wikis
  • create pages
  • edit pages
  • push to wikis
  • clone wikis
email Grants the ability to see the user's primary email address. This should make it easier to use Bitbucket Cloud as a login provider to add-ons or external applications.

This scope gives read access to existing webhook subscriptions on all resources you can access, without needing further scopes. This scope is required for any webhook related operation.

  • list webhook subscriptions on any accessible repository, user, team, or snippet
  • create/update/delete webhook subscriptions

This means that a client can list all existing webhook subscriptions on repository foo/bar (assuming the principal user has access to this repo). The additional repository scope is not required for this.

Likewise, existing webhook subscriptions for a repo's issue tracker can be retrieved without holding the issue scope. All that is required is the webhook scope.

However, to create a webhook for issue:created, the client will need to have both the webhook and the issue scope.

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.

Last modified on Aug 21, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.