From MixxHelp

API Main

Contents 1 User Authentication 1.1 Signing Requests 1.2 Web Authentication 1.3 Desktop Authentication

User Authentication

The user authentication service does not support JSON.

There are currently two ways to authenticate users, depending upon whether your application is web-based or is a desktop application. All calls to the auth service, as well as all calls which require a valid auth_token (which means we're acting on behalf of some user who has gone through this authentication process) must be signed. Let's start by taking a look at how to do that.

Signing Requests

Paired with your API key is a shared secret. It looks a lot like your API key, only a little bit longer. You should treat your shared secret like a password, and ensure that it's never shared with anyone. Mixx will never ask you to reveal your shared secret, and it is never required that it be passed in URLs or in POSTed data. You'll need your secret to complete the request signing process.

Essentially, signing a request is a simple matter of building a string including your shared secret and all of your parameters and their values sorted alphabetically by parameter name, and then composing an MD5 hash of this string. For example, if the parameters to our call are '?apple=orange&banana=pear', then our string is:

YOUR_SHARED_SECRETappleorangebananapear

You then create an MD5 hash of the above string, and append this to your request as the 'api_sig' parameter.

You can verify that you are correctly generating method signatures by sending a GET request to the echo service, and including an 'api_sig' parameter. The echo service doesn't require signed requests, but if it sees that you have signed yours it will tell you in your response whether the signature appears valid. For security reasons it cannot show you the signature it calculated, but it can tell you if the one you provided was accepted via the 'api_sig_valid' child element of the 'rsp' response:

<api_sig_valid>true</api_sig_valid>

Web Authentication

In order for web authentication to work, you must have chosen 'web' as your authentication type, and provided a callback URL that the user will be redirected to after they authenticate. The steps to authenticating a user are as follows:

1) Send the user to the following URL (note that since this request is sent from the user's browser and not your application, there is no way to sign the request):

http://api.mixx.com/services/v1r1/auth?api_key=YOUR_API_KEY

2) If the user authorizes authentication, they will be redirected to your provided callback URL, and an 'auth_key' will be passed along with the request:

http://your.application.com/mixx_auth?auth_key=AUTH_KEY

3) You can now use this auth_key to obtain from the API the auth_token that will allow you to act on the user's behalf. Note that you will also receive the user's user_key, which is usually (but not always) their Mixx username:

http://api.mixx.com/services/v1r1/auth?get_token&api_key=YOUR_API_KEY&auth_key=AUTH_KEY&api_sig=API_SIGNATURE

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok" api_version="v1r1">
  <token>AUTH_TOKEN</token>
  <user user_key="some_user"/>
</rsp

4) The user is now authenticated, and you've received their token. You will pass this as the 'auth_token' parameter in requests that require an authenticated user. Note that users can choose to revoke authentication at any time, in which case the token will no longer be valid, and attempts to use it will result in errors.

Desktop Authentication

Coming soon. No, really, I swear.