Developers

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, unlike mm.test.echo which doesn't require signing.

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 <code><a href="/ja/developers/explore_method?method=mm.auth.getFrob" class="plainlink">mm.auth.getFrob</a></code> 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 <code><a href="/ja/developers/explore_method?method=mm.auth.getToken" class="plainlink">mm.auth.getToken</a></code> 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.

Conventions

Encodings

All strings are UTF-8 encoded.

Date and Time formats

All times are in UTC. The format is : YYYY-MM-DD HH:MM:SS. Example: 2007-12-31 23:11:00

Importing Maps

The mm.maps.import request must be a multipart mixed post and the file content is NOT part of the needed signature. This call can not be tested via the method explorer (as it uses HTTP GET).

Exporting Maps

The mm.maps.export request returns a list of URLs for exporting the maps in different formats. Please note that if you want to export a private map you must then sign and auth the call as well to get the the maps.