Lulu.com Accounts

In order to use many of our APIs, your end-user must have a Lulu account.  Several APIs require a specific account type; for example, the publication API requires that the Lulu.com account be an author account.

Purpose

Login to the API with a Lulu.com account.  This provides the user context for all API requests during a given session.  For example, if a typical user interaction for your application requires 5 user steps which generate a total of 7 calls to Lulu's APIs, you would ask your user for their Lulu.com username and password at the beginning of their interaction, call this authentication API to get a user token, and use that token across all 7 calls.

Using the login API brings with it some restrictions that we require our developers to abide by:

1. You may not state or imply that you are Lulu.com or that Lulu.com sponsors or endorses your application.
2. You may not cache or store a user's credentials after you have sent them to Lulu.

POST Arguments

• username -- The email address associated with the Lulu.com account to log in to.
• password -- The password for this account
• responseType -- Either 'json' or 'xml', the format in which to respond to the request.

The authenticator allows API users to login to Lulu.com with a Lulu.com email and password.  Note that despite the request parameter name this is the email address and not the username.  The result of a successful login is an authentication token.

This API is not fully integrated into the developer system yet, and does not require a developer key.  It is also hosted on a separate host.  In the near future, we will fully integrate this API into the developer system, and we will continue to support the current authentication system for at least six months after the integration is done.

Endpoint

https://www.lulu.com/account/endpoints/authenticator.php

JSON Response

{
    "authenticated":true,
    "message":null,
    "authToken":"23b8860e00190de003c8b0628a1e9de5bfbca69aVP1s2HDMu2W+SQ=="
}

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<luluAuthentication>
  <authenticated>true</authenticated>
  <authToken>0cd8d62525dbdb5be7b31019fe01a1d6fa873460mBq2JV2JtbvWfQ==</authToken>
</luluAuthentication>

Errors

If the request fails, you will receive a 200 HTTP response from the server with an explanation of what went wrong

JSON Error Response

{
    "authenticated":false,
    "message":"You have entered an invalid email and/or password.",
    "authToken":null
}

XML Error Response

<?xml version="1.0" encoding="UTF-8"?>
<luluAuthentication>
  <authenticated>false</authenticated>
  <message>You have entered an invalid email and/or password.</message>
</luluAuthentication>

We have done our best to make the error messages meaningful.  Please let us know in the forums if you receive a message that you cannot understand.

Purpose

Determine if the requested account already exists.

QUERY_STRING

• api_key -- Your api key for the Accounts API.  You cannot not request this api key automatically.  You must contact api@lulu.com and we will attach your existing Publication API key to the Account API.  This is a Simple Key-Based Authentication key.

POST Arguments

• auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
• auth_token -- The auth token returned from the authenticator API.

Endpoint

https://apps.lulu.com/api/account/v1/account_exists/email/${email_address}

JSON Response

The response to this API is a simple JSON structure indicating if the user exists or not.

{"exists": true}

Errors

If the auth_user does not match the auth_token, you will receive a 403 HTTP response.

Purpose

Create a new account on Lulu.com

QUERY_STRING

• api_key -- Your api key for the Accounts API.  You cannot not request this api key automatically.  You must contact api@lulu.com and we will attach your Publication API key to your account.  This is a Simple Key-Based Authentication key.

POST Arguments

• auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
• auth_token -- The auth token returned from the authenticator API.
• account -- A JSON Representation of the account

All users created through this API are created with permissions required to publish books.  Future releases will improve the permission system to provide more control to the API user.

Endpoint

https://apps.lulu.com/api/account/v1/create_account

JSON Response

The response to this API is a simple JSON structure indicating if the user was successful created.

{"success": true}

Errors

All errors in this API result in a 500 HTTP response from the server, with the reason for the error in the response body.

{
    "error_value": "An account with this e-mail address already exists.",
    "error_type": "LApiInvalidArgumentsException"
}