Authentication

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:

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:
```
BANANASabcbazfegbaryxzfoo
```

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:

Take the authentication service URL:

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

Append your api_key. We'll use abc123.

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

Append a perms parameter. We'll use delete.
```
https://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).

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

https://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:

Ask them to login with their Remember The Milk 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:

https://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:

Take the authentication service URL:

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

Append your api_key. We'll use abc123.

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

Append a perms parameter. We'll use delete.
```
https://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).

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

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

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

https://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:

Ask them to login with their Remember The Milk 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 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.