Rate this page:
The purpose of this section is to describe how to authenticate when making API calls using the Bitbucket REST API.
Our OAuth 2 implementation is merged in with our existing OAuth 1 in such a way that existing OAuth 1 consumers automatically become valid OAuth 2 clients. The only thing you need to do is edit your existing consumer and configure a callback URL.
Once that is in place, you'll have the following 2 URLs:
1 2https://bitbucket.org/site/oauth2/authorize https://bitbucket.org/site/oauth2/access_token
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.
The full-blown 3-LO flow. Request authorization from the end user by sending their browser to:
1 2https://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:
1 2$ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=authorization_code -d code={code}
This flow is useful for browser-based add-ons that operate without server-side backends.
Request the end user for authorization by directing the browser to:
1 2https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=token
That will redirect to your preconfigured callback URL with a fragment
containing the access token
(#access_token={token}&token_type=bearer) where your page's js can
pull it out of the URL.
Somewhat like our existing "2-LO" flow for OAuth 1. Obtain an access token that represents not an end user, but the owner of the client/consumer:
1 2$ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=client_credentials
If your Atlassian Connect add-on uses JWT authentication, you can swap a JWT for an OAuth access token. The resulting access token represents the account for which the add-on is installed.
Make sure you send the JWT token in the Authorization request header using the "JWT" scheme (case sensitive). Note that this custom scheme makes this different from HTTP Basic Auth (and so you cannot use "curl -u").
1 2$ curl -X POST -H "Authorization: JWT {jwt_token}" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=urn:bitbucket:oauth2:jwt
Once you have an access token, as per RFC-6750, you can use it in a request in any of the following ways (in decreasing order of desirability):
Authorization: Bearer {access_token}access_token={access_token}?access_token={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. This is much like GitHub, yet slightly different:
1 2$ 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 (note the difference with GitHub where the actual token is in
the username field).
Our access tokens expire in one hour. When this happens you'll get 401 responses.
Most access tokens grant responses (Implicit and JWT excluded). Therefore, you should include a refresh token that can then be used to generate a new access token, without the need for end user participation:
1 2$ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=refresh_token -d refresh_token={refresh_token}
Bitbucket's API applies a number of privilege scopes to endpoints. In order to access an endpoint, a request will need to have the necessary scopes.
Scopes are declared in the descriptor as a list of strings, with each string being the name of a unique scope.
A descriptor lacking the scopes element is implicitly assumed to require all scopes and as a result, Bitbucket will require end users authorizing/installing the add-on
to explicitly accept all scopes.
Our best practice suggests you add the scopes your add-on needs, but no more than it needs.
Invalid scope strings will cause the descriptor to be rejected and the installation to fail.
The available scopes are:
Provides access to view the project or projects.
This scope implies the repository scope, giving read access to all the repositories in a project or projects.
This scope is deprecated, and has been made obsolete by project:admin. Please see the deprecation notice here.
Provides admin access to a project or projects. No distinction is made between public and private projects. This scope doesn't implicitly grant the project scope or the repository:write scope on any repositories under the project. It gives access to the admin features of a project only, not direct access to its repositories' contents.
Provides read access to a repository or repositories. Note that this scope does not give access to a repository's pull requests.
Provides write (not admin) access to a repository or repositories. No distinction is made between public and private repositories. This scope implicitly grants the repository scope, which does not need to be requested separately.
This scope alone does not give access to the pull requests API.
Provides admin access to a repository or repositories. No distinction is made between public and private repositories. This scope doesn't implicitly grant the repository or the repository:write scopes. It gives access to the admin features of a repo only, not direct access to its contents. This scope can be used or misused to grant read access to other users, who can then clone the repo, but users that need to read and write source code would also request explicit read or write.
This scope comes with access to the following functionality:
Provides access to delete a repository or repositories.
Provides read access to pull requests.
This scope implies the repository scope, giving read access to the pull request's destination repository.
Implicitly grants the pullrequest scope and adds the ability to create, merge and decline pull requests.
This scope also implicitly grants the repository:write scope, giving write access to the pull request's destination repository. This is necessary to allow merging.
Ability to interact with issue trackers the way non-repo members can. This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository.