Authentication Parameters for all methods

Each API method accepts a set of authentication parameters in addition to its stated arguments:

app_key string
Application key as provided by Eventful
user string
[optional] Eventful username of the client user.
password string
[optional] Cleartext password for the specified user.
user_key string
[optional] user authorization key (see Digest Authentication below)

Application Keys

The application key is an opaque string assigned by Eventful which identifies the application making the method call. This is separate from user authentication, which identifies the Eventful user using the application. For example, if Eventful user harry is using a Dashboard widget to display events from a Smart Calendar, app_key would identify the Dashboard widget and user (and password or user_key) would identify the user.

A valid application key is required for any interaction with the Eventful API. Application developers may request an application key from the Eventful API site.

User Authentication

The API accepts Basic or Digest user authentication, provided as name-value pairs sent along with method parameters. Each method accepts authentication and determines what level of authorization is required for the specific call. For example, a call to users/calendars/get only requires authentication if the requested calendar is marked private by its owner.

Methods may also modify their output based on the authenticated user. For instance, private events, venues, and calendars will only appear in lists requested by their owners. Some methods may also indicate whether information is editable by the current user. See the documentation for each method for specific cases.

Basic Authentication

The Basic level of authentication involves providing the parameters user and password to each method call along with other parameters. For instance:

http://api.evdb.com/rest/venues/get?app_key=...&user=harry&password=H0gwart$&id=...

If a user and password are provided, the API will validate them against the Eventful user database. If the user is valid and authenticated, the method call will continue. If the user is not valid or presented an incorrect password and the method requires authentication, an XML error message is returned:

<error string="Authorization Required">
  <description>'harry' is not a valid user or provided 
    an incorrect password.</description>
</error>

Note that Basic authentication provides very little in the way of password security. As the example above shows, any eavesdropper could easily determine the user's password. Eventful recommends using Digest authentication wherever possible.

Digest Authentication

The (simplified) Digest level of authentication involves calling the login API method to retrieve a user authentication key, then providing the providing the parameters user and user_key to future method calls along with other parameters.

A login API method is provided in order to retrieve a valid user authentication key for a given user. The client application calls the login method with no parameters (aside from a valid app_key):

http://api.evdb.com/rest/users/login?app_key=...

The response, an "Authorization Required" error message, includes the nonce, a value to be used in computing the digest response:

<error string="Authorization Required">
  <nonce>0689559111</nonce>
  <description>Please supply a user authentication response 
    using the nonce provided.</description>
</error>

The digest response is a hex representation of the MD5 digest of nonce and the MD5-encoded password: lowercase( MD5(nonce + ':' + lowercase(MD5(password))). Note that BOTH MD5 encodings need to return a lowercase representation of the hex string. For example, in Perl the code to generate an appropriate response would be:

use Digest::MD5 qw(md5_hex);
$response = lc( md5_hex( $nonce . ":" . lc( md5_hex($password) ) ) );

The client application then calls login again with the user, nonce, and response parameters:

http://api.evdb.com/rest/users/login?app_key=... &user=harry &nonce=0689559111 &response=ea230d9de20eaaa2d8ed286cc71a8442

If the user is not valid or presented an incorrect password, the "Authorization Required" error message is returned as above. If the user is valid, a valid user_key is returned:

<login>
  <user_key>sm2b4330fdPyHpd0</user_key>
</login>

Further method calls proceed similarly to the way Basic authentication works. For instance:

http://api.evdb.com/rest/venues/get?app_key=... &user=harry &user_key=sm2b4330fdPyHpd0 &id=...

If user and user_key are provided, the API will check them against the Eventful user database. If the user and authentication key are valid, the method call will continue. If the user is not valid or presented an invalid user authentication key and the method requires authentication, an XML error message is returned:

<error string="Authorization Required">
  <description>'harry' is not a valid user or provided 
    an incorrect password.</description>
</error>