Developer's API Documentation : Authentication


Authentication

To authenticate, you must first request a session token. This is done via a GET or POST request to the "token.php" API endpoint. Your request for a session token must be signed with your registered AppID. This ensures that nobody can spoof your application. The session token you receive is used to generate a key which will be used on all further API requests.

You can optionally send a few details about your application, which may be helpful for you. These details will be visible to you on the statistics page. This can give you information about what devices your users are using your app on.


http://api.toodledo.com/2/account/token.php?userid=abcdef1234556789;appid=myAppID;
vers=21;device=iphone4;os=401;sig=a1s2d3f4a5s6d7f8a9s0d

If the token request was successful a session token will be returned.

JSON: 
{"token":"1a2b3c4d5e6f7"}

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/account/token.php?userid=abcdef1234556789;appid=myAppID;
vers=21;device=iphone4;os=401;sig=a1s2d3f4a5s6d7f8a9s0d;f=xml

XML: 
<token>1a2b3c4d5e6f7</token>

This token is good for 4 hours. At the end of four hours, you will need to get a new token. Token requests are rate limited, so you should cache the token until it expires. Token requests can be done over an SSL connection for maximum security.


Generating Keys

The session token is used to generate a key that will be required for every other API interaction. The key is generated by using an MD5 hash similar to how we requested a session token. The key is generated with the user's password, your applications registered App Token, and the session token received above.

Generating the key with PHP
$key = md5( md5($userPassword).$appToken.$sessionToken );

Generating the key with C
key = md5( md5(userPassword)+appToken+sessionToken );

This key must be sent in all future API calls to authenticate yourself.

If you are having trouble authenticating, make sure you notice that the password is hashed once before you concatenate it with the other variables, and then the entire thing is hashed again. Also, make sure your md5 function is returning a 32 character hexadecimal string.

Testing
To test your md5 function, we would expect the md5 hash of the string "test" to be 098f6bcd4621d373cade4e832627b4f6. For your convienence, this form will generate a signature for testing purposes.
App Token:
User Password:
Session Token:



Account Lookup

To authenticate with the API and perform any action on a user's account, you will need to have their userid and Toodledo password. This is done via a GET or POST request to the "lookup.php" API endpoint. The user can give you this information directly since their userid is available to them on the website, or you can lookup the userid from their email/password. The userid will not change, so you should do the lookup once and cache the userid forever. To avoid sending the user's password in the clear, you should use an SSL connection if possible.


http://api.toodledo.com/2/account/lookup.php?appid=MyAppID;sig=1a2b3c4d5e6f7;
	email=test@example.com;pass=mypassword

If the lookup was successful a userid will be returned.

JSON: 
{"userid":"1a2b3c4d5e6f7"}

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/account/lookup.php?f=xml;appid=MyAppID;sig=1a2b3c4d5e6f7;
	email=test@example.com;pass=mypassword

XML: 
<userid>1a2b3c4d5e6f7</userid>


Account Creation

If your user does not have a Toodledo account, you can create one for them using the API. This is done via a GET or POST request to the "create.php" API endpoint. Simply ask your user for the email and password that they wish to use and the account will be created and ready to use for syncing. To avoid sending the user's password in the clear, you should use an SSL connection if possible.


http://api.toodledo.com/2/account/create.php?appid=MyAppID;sig=1a2b3c4d5e6f7;
	email=test@example.com;pass=mypassword

If the account was created a userid will be returned.

JSON: 
{"userid":"1a2b3c4d5e6f7"}

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/account/create.php?f=xml;appid=MyAppID;sig=1a2b3c4d5e6f7;
	email=test@example.com;pass=mypassword

XML: 
<userid>1a2b3c4d5e6f7</userid>


Error Codes

Any of the API calls can return error messages. Here is a list of the error messages that you may receive from the account API.



Examples:
JSON:
{"errorCode":1,"errorDesc":"Empty key"}

XML:
<error id="5">Invalid appid</error>
Toodledo.com | API Home | Forums | Contact Us | Blog | Jobs | Press | Privacy | Terms | Copyright © 2006-2014  4