What is OAuth?
OAuth is an open protocol that allows applications and websites to share sensitive data, without requiring you to release your password. Using OAuth, you can permit third-party applications to read from and write to your Ohloh account without having to share your secret password.
Instead of handing out your Ohloh account password to a third-party application, you visit the Ohloh website directly and grant that application permission to access your Ohloh account. You can revoke this permission any time you change your mind.
NOTE: At present, Ohloh does not include any writeable API calls. This documentation page is a placeholder for future functionality.
Developer Information
OAuth is an optional, additional feature of the Ohloh API. You can read public data from Ohloh at any time using only your application’s Ohloh API Key.
If you need to read confidential Ohloh account information, or if you would like to write new data to Ohloh, you must obtain an OAuth access token. This requires your application to be specifically granted permission by the Ohloh account holder.
When you provide an OAuth access token to the Ohloh API, Ohloh will behave as if you are logged in as the authorizing account. Any edits you make to Ohloh using that access token will appear as if they were made by the authorizing account.
Step-By-Step Example
This example will guide you through creating a connection to Ohloh using the OAuth RubyGem. The steps should be similar if you are using another OAuth library.
First, if you have not already done so, you must register your application with Ohloh and obtain an API Key. You can see your list of registered applications at http://www.ohloh.net/accounts/me/api_keys.
Your oauth_consumer_key is the same as your Ohloh API Key. When you use an OAuth authentication header, you do not need to pass the usual api_key parameter, because Ohloh can determine your API Key by examining the OAuth header.
Once you have an API Key (oauth_consumer_key), you must prompt the account holder to authorize your application to access his account. You do this by obtaining a request token.
Here’s how to obtain a request token using Ruby:
gem 'oauth' require 'oauth/consumer' @consumer = OAuth::Consumer.new("your api key", "your oauth consumer secret", :site => "http://www.ohloh.net") @request_token = @consumer.get_request_token This creates an authorization request on Ohloh. You must now prompt the user to approve this request by visiting the Ohloh web site.
The request token contains the appropriate URL for the user to visit. You can redirect the user there directly, or you may simply instruct the user to visit this URL using a web browser:
@request_token.authorize_url You may append an optional oauth_callback_url parameter to this URL. If you do, then after the user approves the request, the user will be redirected to this URL.
Once approved, you must now exchange your request token for an access token. The access token is what actually gives you permission to read and write to Ohloh:
@access_token = @request_token.get_access_token For example, you can now post journal messages to this user’s account:
@access_token.post '/accounts/me/messages.xml', 'message[body]' => 'this message was posted via the Ohloh API using OAuth' There are two things to notice about the URL used to post:
First, the me account shortcut was used. This is because when you use OAuth, you will be automatically “logged in” as the authenticating user, so the me shortcut automatically resolves to the correct account.
Second, be sure to append the .xml extension to the URL. This ensures that you are accessing the Ohloh API web site. If you omit the .xml extension, the server will assume you are using a web browser, and may attempt to redirect you or return javascript code instead of properly processing your request.
If you need any help using OAuth with the Ohloh API, you can find help in our forums or send mail to info@ohloh.net.
Technical Notes
Ohloh exposes the following URLs for the standard OAuth operations:
http://www.ohloh.net/oauth/authorize http://www.ohloh.net/oauth/request_token http://www.ohloh.net/oauth/access_token http://www.ohloh.net/oauth/test_request Ohloh supports only the HMAC-SHA1 signature method. All requests must be signed.
