Authentication

Signing Requests

Let's presume that our shared secret is DEADBEEF. To sign a request, you need first to sort your parameters by key name, so that:

yxz=foo feg=bar abc=baz

becomes:

abc=baz feg=bar yxz=foo

Construct a string with all key/value pairs concatenated together:

abcbazfegbaryxzfoo

Concatenate the previous result onto your shared secret:

DEADBEEFabcbazfegbaryxzfoo

Calculate the MD5 hash of this string:

md5('DEADBEEFabcbazfegbaryxzfoo') -> 75178b3c27252027ae97b9a5eb36ce41

We now use this result (<code>75178b3c27252027ae97b9a5eb36ce41</code>) as our <code>api_sig</code> parameter.

User authentication for web-based applications

To authenticate users for your web-based application, construct an authentication URL as follows:

Take the authentication service URL:

http://www.mindmeister.com/services/auth/

Append your <code>api_key</code>. We'll use <code>abc123</code>.

http://www.mindmeister.com/services/auth/?api_key=abc123

Append a <code>perms</code> parameter. We'll use <code>delete</code>.

http://www.mindmeister.com/services/auth/?api_key=abc123&perms=delete

Valid <code>perms</code> values are:

• read – gives the ability to read task, contact, group and list details and contents.
• write – gives the ability to add and modify task, contact, group and list details and contents (also allows you to read).
• delete – gives the ability to delete tasks, contacts, groups and lists (also allows you to read and write).

Now sign your parameters as detailed above and append an api_sig.

http://www.mindmeister.com/services/auth/?api_key=abc123&perms=delete&api_sig=zxy987

You now have a valid authentication URL. Continue reading what to do next.

User authentication for desktop applications

Desktop application authentication is pretty much identical to the above, but, instead of being redirected to a callback URL with a frob, we first make a call to mm.auth.getFrob and pass the result as a <frob> parameter in our authentication URL.

So, first of, we call mm.auth.getFrob, and it returns an element:

<rsp stat="ok">
                <frob>123456</frob>
                </rsp>

Then, construct an authentication URL as follows. First take the authentication service URL:

http://www.mindmeister.com/services/auth/

Append your api_key. We'll use abc123.

http://www.mindmeister.com/services/auth/?api_key=abc123

Append a perms parameter. We'll use delete

http://www.mindmeister.com/services/auth/?api_key=abc123&perms=delete

Valid perms values are:

• read – gives the ability to read task, contact, group and list details and contents.
• write – gives the ability to add and modify task, contact, group and list details and contents (also allows you to read).
• delete – gives the ability to delete tasks, contacts, groups and lists (also allows you to read and write).

Append your frob from before. We'll use 123456.

http://www.mindmeister.com/services/auth/?api_key=abc123&perms=delete&frob=123456

Now sign your parameters as detailed above and append an api_sig.

http://www.mindmeister.com/services/auth/?api_key=abc123&perms=delete&frob=123456&api_sig=zxy987

Using an authentication well

Voilà! An authentication URL. Point your application user at this URL, and MindMeister will:

• Ask them to login with their MindMeister credentials, if they're not already logged in, and then...
• Ask them if they wish to give your application access to their account (with the permissions you asked for).

If the user authorizes your application, they are then instructed to return to your application so that the authorization process may be completed.

Your application should now make a call to mm.auth.getToken with a frob parameter (the one you received from mm.auth.getFrob). You'll get back an <auth> element with a token (you use this as the auth_token parameter for all further authenticated API calls) and some user information, like so:

<rsp stat="ok">
                <auth>
                <token>410c57262293e9d937ee5be75eb7b0128fd61b61</token>
                <perms>delete</perms>
                <user id="1" username="till_vollmer" fullname="Till Vollmer" />
                </auth>
                </rsp>

That's it! You may now call as many methods as you like.

Verifying token validity

auth_token can and do expire (for example, if the user revokes the permissions they granted to your application). To check the validity of your auth_token, call mm.auth.checkToken with your auth_token as a parameter. If your auth_token is still valid, you'll get a success response back:

<rsp stat="ok">
                <auth>
                <token>410c57262293e9d937ee5be75eb7b0128fd61b61</token>
                <perms>delete</perms>
                <user id="1" username="till_vollmer" fullname="Till Vollmer" />
                </auth>
                </rsp>

If your auth_token has expired, you'll receive:

<rsp stat="fail">
                <err code="98" msg="Login failed / Invalid auth token" />
                </rsp>

And you'll need to get a new token.