Skip to end of metadata
Go to start of metadata

Overview

Use these endpoints to negotiate an OAuth session on behalf of a user. These endpoints are the client side calls necessary to interact with the Bitbucket server. You need an existing consumer key to make these calls. To obtain a consumer key, use the oauth resource on the users endpoint or use the Integrated Applications menu option on your account.

The methods described in this section represents the methods needed to achieve a complete OAuth authentication flow as depicted here:

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 can be found on the official oauth.net 'code' section.

POST a new request token

Obtains an OAuth request token from the Bitbucket service. Your application uses the values in the response to request user authorization. This method process A of the OAuth 1.0a authentication flow. You pass the following parameters in the header to this request:

ParameterRequiredDescription
oauth_consumer_keyYesThe consumer key. This value is generated by Bitbucket.
oauth_nonceYes

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_signatureYesThe 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_methodYesThe signature method the consumer used to sign the request. This is determined by your application.
oauth_timestampYesThe 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_callbackYes

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

POST https://bitbucket.org/!api/1.0/oauth/request_token

Make a call to the service:

https://bitbucket.org/!api/1.0/oauth/request_token?oauth_signature=FLH4XvS50eewsdV2ce98Nz0FFic=&oauth_consumer_key=ygzpJGqUpGn95nVw8s&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1346265284&oauth_nonce=QQo7CT&oauth_callback=https://www.myapplication.com

Receive back:

oauth_token=Z6eEdO8lOmk394WozF9oJyuAv899l4llqo7hhlSLik&oauth_token_secret=Jd79W4OQfb2oJTV0vzGzeXftVAwglnEJ9lumzYcl&oauth_callback_confirmed=true

GET user authorization

Use an OAuth request_token to request user authorization. If the user is currently logged in, the call uses the user's the account for access authorization. You pass the following parameters to this request:

ParameterRequiredDescription
oauth_tokenYesA request token returned by Bitbucket.
GET https://bitbucket.org/!api/1.0/oauth/authenticate

Send the user to the oauth/authenticate step in a web browser, including an oauth_token parameter received from the request_token call:

https://bitbucket.org/!api/1.0/oauth/authenticate?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik

POST an access token

Allows a consumer application to exchange an OAuth request token for an OAuth access token.  You pass the following parameters to this request:

ParameterRequiredDescription
oauth_consumer_keyYesThe consumer key. This value is generated by Bitbucket.
oauth_tokenYesThe oauth_token returned by the request_token call.
oauth_nonceYes

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_signatureYesThe 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_methodYesThe signature method the consumer used to sign the request. HMAC-SHA1 is the method supported by Bitbucket.
oauth_timestampYesThe 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_verifierYes

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

POST https://bitbucket.org/!api/1.0/oauth/access_token

A response to a successful request appears as follows:

oauth_token_secret=aH9bzCKjKT5uXWueeENr9LKNh2jyyUVj&oauth_token=NqFQPmgsa4QQ9StW2R

 

 


4 Comments

  1. Anonymous

    Created an app in PHP and everything works fine (on localhost). Copied the exact same source code to "live" server and it gets stuch by request_token. It returns 400 Bad Request - Could not verify OAuth request.

    Any ideas?!?

    1. Sorry you are having problems with this.  The quickest route to direct and personal help is support@bitbucket.org 

      Mary

  2. Anonymous

     

     missed a "oauth_verifier" parameter in "POST an access token"

  3. Anonymous

    The oauth_verifier seems to be only provided via the callback.