OAuth FAQ


What is OAuth?

OAuth is an open standard for authorization.  OAuth allows one program to authorize another program to make changes on behalf of an account holder or end-user.  You only need OAuth if you want to write a program that uses Bitbucket resources.  


What is an OAuth consumer?

If you want to write an application that uses Bitbucket, you need an OAuth consumer.   A consumer is a key and secret pair that an application uses to identify itself to Bitbucket.  This is an example of what a key and secret look like:

 MtDjb9nNZayJR3T5HJ
NWGALX95qQKTBNS8Ea6kyINEmEmNUrk9



Where do I get an OAuth consumer?

Any Bitbucket account holder can create a consumer. To get a consumer:

  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.

Alternatively, you can create a consumer using the oauth Resource on the users Endpoint.


Should my sample OAuth source code include my keys?

No. Do not share your consumer key with other users. They are the equivalent of sharing your username/password combination and we hope you wouldn't do that either!

Instead, we recommend you use variables for your secret and key. People that fork your code can replace these with their own when testing.  You could also write your code to pull these values from a separate configuration file.  Just tell people the format of the file.


Do I have granular control of OAuth permissions (scopes)?

No. Bitbucket does not provide scopes.  Your application will act on behalf of the account holder with that holder's full rights to act on the account's repositories.

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