API > Authentication

To use the MindMeister API and authenticate users, you first need an API Key.

With the API key, you'll also receive a shared secret that is used to sign (on your end) and verify (on our end) requests.

The majority of the MindMeister API methods require requests to be signed - mm.test.echo does not require signing.

Signing Requests

Let's presume that our shared secret is DEADBEEF. To sign a request, you need to:

1. Sort your parameters by key name, so that:

   yxz=foo feg=bar abc=baz

   
   becomes:

   abc=baz feg=bar yxz=foo

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

   abcbazfegbaryxzfoo

   
   
3. Concatenate the previous result onto your shared secret:

   DEADBEEFabcbazfegbaryxzfoo

   
   
4. Calculate the MD5 hash of this string:

   md5('DEADBEEFabcbazfegbaryxzfoo') -> 75178b3c27252027ae97b9a5eb36ce41

   
   

We now use this result, 75178b3c27252027ae97b9a5eb36ce41 as our api_sig parameter.

User authentication for web-based applications

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

1. Take the authentication service URL:

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

   
   
2. Append your api_key. We'll use abc123.

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

   
   
3. 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).
4. 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

   
   

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 redirected to your callback URL with a frob parameter, like so:

http://www.example.com/mindmeister.php?frob=456abc123xyz987opq

Your application should now make a call to mm.auth.getToken with a frob parameter as passed to the callback URL. 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>

And you're good to go. Simple, right?

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:

1. Take the authentication service URL:

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

   
   
2. Append your api_key. We'll use abc123.

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

   
   
3. 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).
4. Append your frob123456.

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

   
   
5. 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

   
   

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.

Back