API: Authentication / OAuth

For user authentication via the API, we are using OAuth version 1.0a. This is a standard with growing acceptance that has a good balance of security and ease-of-use. By leveraging the OAuth libraries available in most programming languages, third-party developers should be able to authenticate with the Obsidian Portal API very easily.

OAuth Overview

Rather than say what's already been said, we'll direct you instead to Twitter's excellent OAuth overview. Pay special attention to the diagram and make sure you understand all the steps. If you're still confused, here is a more in-depth analysis of OAuth.

By far, the majority of OAuth issues we deal with are related to people not understanding the OAuth workflow. Getting a handle on it from the start will go a long way to making your app development much easier.

Authorization URLs

Our API exists on the api subdomain, but due to cookie and SSL restrictions, we have to do authorization and authentication via the www subdomain. Our relevant OAuth URLs are as follows:

Get Request Token Url

https://www.obsidianportal.com/oauth/request_token

Authorize User Url

https://www.obsidianportal.com/oauth/authorize

Get Access Token Url

https://www.obsidianportal.com/oauth/access_token

Signature Method

The only signature method we support is HMCA-SHA1

Mobile / Desktop / Out of Band Applications

OAuth is not as friendly to mobile and desktop (aka. "Out of Band" or "oob") applications as it is to web apps, but it's still possible. Here are a few tips and FAQs for dealing with these

Verifier / PIN / Verification Code

After sending a user to the Authorize User URL, you will need a Verifier in order to exchange the Request Token for an Access Token. With web apps, this is automatically sent back to the application, but with Out of Band apps, it will be displayed to the user on the authorize page. They will need to copy the displayed PIN and paste it into your app. This is the OAuth Verifier needed for the final step.

In addition, if you are using an embedded browser inside your Out of Band app, it is possible to automatically retrieve the verifier using Javascript, thereby avoiding the need for the user to copy and paste it by hand. The PIN is embedded in the resulting HTML with an element ID of oauth-verifier.

Resources