欢迎使用！  中文 (简体) Language Switcher

To use the Remember The Milk 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 Remember The Milk API methods require requests to be signed — rtm.test and rtm.time methods do not require signing.

Signing Requests

Let's presume that our shared secret is BANANAS. 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: 

    BANANASabcbazfegbaryxzfoo


  4. Calculate the MD5 hash of this string: 

    md5('BANANASabcbazfegbaryxzfoo') -> 82044aae4dd676094f23f1ec152159ba


We now use this result, 82044aae4dd676094f23f1ec152159ba 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.rememberthemilk.com/services/auth/


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

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


  3. Append a perms parameter. We'll use delete. 

    http://www.rememberthemilk.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.rememberthemilk.com/services/auth/?api_key=abc123&perms=delete&api_sig=zxy987


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

If the user authorizes your application, they are then redirected to your callback URL with a frob parameter, like so:

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

Your application should now make a call to rtm.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="bob" fullname="Bob T. Monkey" />
  </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 rtm.auth.getFrob and pass the result as a frob parameter in our authentication URL.

So, first of, we call rtm.auth.getFrob, and it returns a <frob> element:

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

Then, construct an authentication URL as follows:

  1. Take the authentication service URL: 

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


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

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


  3. Append a perms parameter. We'll use delete. 

    http://www.rememberthemilk.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 frob from before. We'll use 123456. 

    http://www.rememberthemilk.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.rememberthemilk.com/services/auth/?api_key=abc123&perms=delete&frob=123456&api_sig=zxy987


Voilà! An authentication URL for desktop applications. Point your application user at this URL, and Remember The Milk will:

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 rtm.auth.getToken with a frob parameter (the one you received from rtm.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="bob" fullname="Bob T. Monkey" />
  </auth>
</rsp>

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

Verifying token validity

auth_token's 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 rtm.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="bob" fullname="Bob T. Monkey" />
  </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.