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.

  • userid : A hexadecimal string identifying a single user who is using your app. A user can give this to you directly, or you can look it up via the account/lookup API method. (required)
  • appid : A text string identifying your application. (required)
  • vers : An integer representing the version number of your application. (optional)
  • device : A text string identifying the device or platform that your application runs on. (optional)
  • os : An integer identifying the operating system version number of the device or platform that your application runs on. (optional)
  • sig : A signature to validate your application. Generated by taking the md5 hash of the userid and your App Token. The App Token was generated when you registered your app. (required)

    Generating the signature with PHP
    $sig = md5( $userid.$myAppToken );

    Generating the signature with C
    sig = md5( userid+myAppToken );

    Generating the signature with Obj-C
    char *cStr = [[NSString stringWithFormat:@"%@%@",userid,myAppToken] UTF8String];
    unsigned char result[CC_MD5_DIGEST_LENGTH];
    CC_MD5(cStr, strlen(cStr), result);
    NSString *sig = [NSString stringWithFormat: @"%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X", result[0], result[1], result[2], result[3], result[4], result[5], result[6], result[7], result[8], result[9], result[10], result[11], result[12], result[13], result[14], result[15]];

    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.
    Userid:
    App Token: 

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.

  • appid : Your registered AppID. (required)
  • email : The email address that the user registered with Toodledo. (required)
  • pass : The user's Toodledo password. (required)
  • sig : A signature to authenticate the request. Generated by taking the md5 hash of the email and your App Token. The App Token was generated when you registered your app. (required)

    Generating the signature with PHP
    $key = md5( $email.$myAppToken );

    Generating the signature with C
    key = md5( email+myAppToken );

    Generating the signature with Obj-C
    char *cStr = [[NSString stringWithFormat:@"%@%@",email,myAppToken] UTF8String];
    unsigned char result[CC_MD5_DIGEST_LENGTH];
    CC_MD5(cStr, strlen(cStr), result);
    NSString *sig = [NSString stringWithFormat: @"%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X", result[0], result[1], result[2], result[3], result[4], result[5], result[6], result[7], result[8], result[9], result[10], result[11], result[12], result[13], result[14], result[15]];

http://api.toodledo.com/2/account/lookup.php?appid=MyAppID;sig=1a2b3c4d5e6f7;
	[email protected];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 protected];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.

  • appid : Your registered AppID. (required)
  • email : The email address that the user registered with Toodledo. (required)
  • pass : The user's Toodledo password. (required)
  • sig : A signature to authenticate the request. Generated by taking the md5 hash of the email and your App Token. The App Token was generated when you registered your app. (required)

    Generating the signature with PHP
    $key = md5( $email.$myAppToken );

    Generating the signature with C
    key = md5( email+myAppToken );

    Generating the signature with Obj-C
    char *cStr = [[NSString stringWithFormat:@"%@%@",email,myAppToken] UTF8String];
    unsigned char result[CC_MD5_DIGEST_LENGTH];
    CC_MD5(cStr, strlen(cStr), result);
    NSString *sig = [NSString stringWithFormat: @"%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X", result[0], result[1], result[2], result[3], result[4], result[5], result[6], result[7], result[8], result[9], result[10], result[11], result[12], result[13], result[14], result[15]];

http://api.toodledo.com/2/account/create.php?appid=MyAppID;sig=1a2b3c4d5e6f7;
	[email protected];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 protected];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.

  • 1 : You did not specify a key for authentication.
  • 2 : The authentication key that you provided as expired or is invalid.
  • 3 : No userid specified when getting a token.
  • 4 : No AppId specified.
  • 5 : Invalid AppID. You must register an AppID before you can use it.
  • 6 : Invalid Userid. The specified user was not found
  • 7 : Excessive Tokens. Your app has requested too many tokens for this user in a short amount of time. You should cache and use a token until it expires.
  • 8 : No signature. You must sign a token request to validate it.
  • 9 : Invalid signature. The signature that you included is invalid.
  • 10 : The email address was left blank.
  • 11 : The password was left blank.
  • 12 : The email/password was invalid.
  • 100 : Unknown Error.
  • 400 : Your app has been blocked by the user.
  • 500 : The Toodledo server is offline for maintenance.


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


XML:
<error id="5">Invalid appid</error>