API: Authentication / OAuth
UPDATE 10/31/2024 - The API Authorization is currently broken, so the API itself is not currently usable. The plan is to upgrade to OAuth 2.0, but we do not currently have an estimate of when that will happen.
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.