• Overview
• Getting Started
  Step 1: Add New Application Step 2: Authenticate User Step 3: Access REST API Step 4: Get Support Appendix: A Sample Application
• API Endpoints
  Users Media Feeds Checkins Badges Episodes Notifications
• SDK and Tools
  iOS SDK
• OAuth Authentication
• Sample Code
• Widgets and Feeds
• Support
• Rules of Use
• Engineering Blog

Miso API Authentication

The Miso API supports authentication of third-party applications using the OAuth protocol. This allows your application to access a user's data and perform actions on behalf of the user (after they have explicitly granted permission).

The easiest way to interact with OAuth is to utilize already available OAuth libraries which abstract the need to understand the specifics of the OAuth exchange process. Download a library from the OAuth Code page and look at the Getting Started guide for a quick run through. A more detailed procedure for making requests with OAuth is as follows:

Register New Application

You’ll need to register your application with Miso to get your unique Application Key. Click on “Manage Applications” in the upper right hand corner of this page, screenshot below.

Click on “Register an Application” and fill out the form. The callback URL is the address a user will be redirected to after they authenticate with Miso. If you’re creating a mobile application, you don’t need to specify a callback URL here.

Getting OAuth Access (Standard)

You’ll want users to authorize your application to read their check-in history or to check-in to a TV show or movie. Miso uses OAuth for authentication. In order to authenticate a user in your application, you’ll need to do the following:

1. Fetch a request token, by using the request token URL: https://gomiso.com/oauth/request_token/ signed with your consumer credentials. You must include an oauth_callback parameter. The response will include a key and secret for a request token.
2. Redirect the user to the authorization url:
   https:/gomiso.com/oauth/authorize?oauth_token=request_token_key.
3. After authorizing, the user is redirected to your callback url with the oauth_token and an oauth_verifier parameter that your application will need acquire an access token.
4. Fetch an access token using the access token URL: https://gomiso.com/oauth/access_token. If the user has chosen to allow the application and a correct oauth_verifier parameter is supplied, the request will return an access token key and secret which can be used for subsequent requests.
5. Make API calls as normal with the necessary OAuth parameters or headers added to the request.

Signatures are used to ensure the identity of the consumer application. Currently, the Miso implementation of OAuth supports HMAC_SHA1 as the signature method.

Getting OAuth Access (xAuth)

In addition to the standard OAuth authentication flow, Miso also supports the xAuth mechanism for authentication. Keep in mind that xAuth is still OAuth and signed requests must still be sent.

xAuth provides a method for desktop and mobile apps to exchange a username and password directly for an OAuth access token. Once the access token is retrieved, the client application should dispose of the login and password for the user. The steps are as follows:

1. In your client application, prompt the user for their Miso username and password and store them in a temporary location.
2. Fetch an access token using the access token URL: https://gomiso.com/oauth/access_token. This can be done by passing the following as post parameters along with the request:
   x_auth_username=<username>&x_auth_password=<password>&x_auth_mode=client_auth
3. If the user's login credentials are correct, the last request will return an access token key and secret which can be used for subsequent requests to the API. Discard the username and password after request is completed.
4. Make API calls as normal with the necessary OAuth parameters or headers added to the request.

Signatures are used to ensure the identity of the consumer application. Currently, the Miso implementation of OAuth supports HMAC_SHA1 as the signature method. For more information on the xAuth mechanism, check out the Twitter xAuth Reference and Twitter xAuth – The Missing Docs

Learn More

For complete details on how to form signatures for OAuth requests, refer to the following guides:

1. OAuth specification details
2. Getting Started with OAuth
3. Hueniverse OAuth Guide
4. Vimeo's OAuth Documentation

Fortunately, there are OAuth libraries available for most major languages that make it easy to get request and access tokens. Check out the Getting Started guide to see this process in action.