OAuth on Bitbucket Cloud

Bitbucket Cloud REST API integrations, and Atlassian Connect for Bitbucket add-ons, can use OAuth 2.0 or 1.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.

Our OAuth 2.0 implementation is merged with our existing OAuth 1.0 in such a way that existing OAuth 1 consumers automatically become valid OAuth 2 clients.

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. Log into your Bitbucket account.
  2. Click avatar > Bitbucket settings from the menu.
    The Account page appears.
  3. Click OAuth from the menu bar.
    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.
  4. Click Save
    The system generates a key and a secret for you.
  5. Toggle the consumer name to see the generated Key and Secret value for your consumer.

Optionally, you could also obtain a consumer using the oauth Resource on the users Endpoint - 1.0.

Access tokens

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

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

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

  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 one hour. 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.

The following scopes are available:

Scope name Description
account

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

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

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
team

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
team:write

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

  • manage team permissions
repository

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

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
repository:admin

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
pullrequest

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
pullrequest:write

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
snippet

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
snippet:write

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
issue

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
issue:write

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

wiki

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.
webhook

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.

OAuth 1.0

Bitbucket Cloud authenticates your application and authorizes access using the OAuth 1.0a with HMAC-SHA1 (shared secret) signatures. We support both 3-Legged and 2-Legged OAuth. RSA-SHA1 (the public/private keys feature) is  not  currently supported.  

If you are building a new client, integration, or Atlassian Connect for Bitbucket add-on we strongly suggest using OAuth 2.0 as the preferred authentication method.

This section steps you through the basic OAuth 1.0a work flow of registering your consumer and getting set up to make API calls. It is difficult to test this work flow with curl. If you don't want to write a quick client, you can try it for yourself interactively using a testing site. The site will create the more complex, calculated values OAuth needs (such as timestamps) for you.

Finally, you should use an existing OAuth library for your application instead of implementing the protocol yourself. Numerous reusable libraries in many languages exist for use with OAuth – they are listed on the official oauth.net site.

Step 1. Create an OAuth key and secret

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. Log into your Bitbucket account.
  2. Click avatar > Bitbucket settings from the menu.
    The Account page appears.
  3. Click OAuth from the menu bar.
    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.
  4. Click Save
    The system generates a key and a secret for you.
  5. Toggle the consumer name to see the generated Key and Secret value for your consumer.

Optionally, you could also obtain a consumer using the oauth Resource on the users Endpoint - 1.0.

Step 2. Request a request token from Bitbucket Cloud

Your application first needs to get an OAuth request token from Bitbucket. It does this through a POST request to https://bitbucket.org/api/1.0/oauth/request_token . Your POST must include:

Parameter Required Description
oauth_consumer_key Yes The consumer key. This value is generated by Bitbucket.
oauth_nonce Yes

A random string, uniquely generated for each request. The nonce allows the Service Provider to verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel (such as HTTP).

oauth_signature Yes The signature as defined by the consumer. OAuth does not mandate a particular signature method, as each implementation can have its own unique requirements. Currently, Bitbucket only supports HMAC-SHA1 or PLAINTEXT signatures.
oauth_signature_method Yes The signature method the consumer used to sign the request. This is determined by your application.
oauth_timestamp Yes The number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value MUST be a positive integer and MUST be equal or greater than the timestamp used in previous requests. If the timestamp is not within a few minutes either side of the actual current time, the request may be rejected.
oauth_callback Yes

The URL to redirect a user to should they approve your application's access to their account. For example:

http%3A%2F%coolapp.local%2Fauth.php,bitbucketclient%3A%2F%2Fcallback

The following is an example of a POST call:

https://bitbucket.org/api/1.0/oauth/request_token?oauth_version=1.0&oauth_nonce=7f2325b3c36bd49afa0a33044d7c6930&oauth_timestamp=1366243208&oauth_consumer_key=HUpRcDUduZrepL6sYJ&oauth_callback=http%3A%2F%2Flocal%3Fdump&oauth_signature_method=HMAC-SHA1&oauth_signature=qZyTwVA48RzmtCHvN9mYWmlmSVU%3D

Bitbucket validates your request and responds with a set of temporary credentials:

HTTP/1.1 200 OK
Server: nginx/1.2.4
Date: Thu, 18 Apr 2013 15:56:00 GMT
Content-Type: application/x-www-form-urlencoded
Content-Length: 112
Connection: keep-alive
X-Served-By: bitbucket05
Content-Language: en
X-Static-Version: 209da49a2dfa
Vary: Accept-Language, Cookie
X-Version: 913e0af5d84d
ETag: "cd2fb61a6e2ac48da4b1c3b377aca5d7"
X-Request-Count: 260
Strict-Transport-Security: max-age=2592000
X-Content-Type-Options: nosniff
oauth_token_secret=3PddbU47vqStvrFag8Dwnpqs28HxAKeq&oauth_token=4vyW6b49ZxcZDK64eY&oauth_callback_confirmed=true

These credentials are the following:

Value Description
oauth_token_secret

The token shared-secret.

oauth_token

The request token.

oauth_callback_confirmed
Must be present and true.

Step 3. Redirect the user to Bitbucket Cloud to authorize your application

Access tokens allow your application to interact with Bitbucket on behalf of user. Before your application can get access tokens, the Bitbucket user must authorize your application to act on his/her behalf. To get authorization, your webserver makes a GET to https://bitbucket.org/api/1.0/oauth/authenticate and passes the oauth_token (request token) returned in the last step's POST. For example, the following call:

https://bitbucket.org/api/1.0/oauth/authenticate?oauth_token=4vyW6b49ZxcZDK64eY

If the user isn't logged into Bitbucket, Bitbucket asks the user to login. In this way, your application verifies the identity of the account holder. Then, Bitbucket confirms with the user that your application should have account access:


Bitbucket then redirects the user to the callback provided in the previous Step 2 above. Bitbucket returns in the redirect an oauth_verifier along with the oauth_token your application provided in its request.

http://localhost/?dump&oauth_verifier=2287965216&oauth_token=URjPjc8CxLgNBdh7zL

Your application should store the oauth_verifier so you can use it in the next step. Bitbucket requires use of the oauth_verifier which is an OAuth 1.0a feature.

Step 4. Request an Access Token

The last step is to obtain credentials that let you access resources on Bitbucket. Your application gets these by making a POST call to https://bitbucket.org/api/1.0/oauth/access_token . Your application must construct a request URI by adding the following parameters:

Parameter Required Description
oauth_consumer_key Yes The consumer key. This value is generated by Bitbucket.
oauth_token Yes The oauth_token returned by the request_token call.
oauth_nonce Yes

A random string, uniquely generated for each request. The nonce allows the Service Provider to verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel (such as HTTP).

oauth_signature Yes The signature as defined by the consumer. OAuth does not mandate a particular signature method, as each implementation can have its own unique requirements. Currently, Bitbucket only supports HMAC-SHA1 signatures.
oauth_signature_method Yes The signature method the consumer used to sign the request. HMAC-SHA1 is the method supported by Bitbucket.
oauth_timestamp Yes The number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value MUST be a positive integer and MUST be equal or greater than the timestamp used in previous requests. If the timestamp is not within a five minutes either side of the actual current time, the request may be rejected.
oauth_verifier Yes

This value is returned as a query parameter in the URL that the token authorization page redirects to after the user clicked "grant permission" on Bitbucket. For example:

http://localhost?oauth_verifier=0352671347&oauth_token=QAx6g4npas3tdARQUY

An example of this request is:

https://bitbucket.org/api/1.0/oauth/access_token?oauth_version=1.0&oauth_nonce=d6d773f282740f2b25112f819b0d3b7c&oauth_timestamp=1366242978&oauth_consumer_key=HUpRcDUduZrepL6sYJ&oauth_verifier=2287965216&oauth_token=YRpuxpCLYCJpXJyUE2&oauth_signature_method=HMAC-SHA1&oauth_signature=vmJ3LuudxaW5Rs7xLJa56TLZwPE%3D

The request returns an access token such as the following:

oauth_token_secret=aH9bzCKjKT5uXWueeENr9LKNh2jyyUVj&oauth_token=NqFQPmgsa4QQ9StW2R

With this access token your application can make Bitbucket API calls.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport