Authentication Parameters for all methods

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

app_key string
[required] Application key as provided by Eventful
oauth_fieldsstring
[optional or required depending on specific API call] Oauth parameters (token,signature,etc).

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.

oAuth

Eventful supports oAuth 1.0 for Eventful API clients to access API resources on behalf of Eventful users.

Your application must first register as an oAuth consumer. To register an application, select [get oAuth consumer] for the application's key at API Application Keys. Your consumer key and consumer secret should be listed under your application key. You will need all three in order to use oAuth.

To access a user's protected resources, that user must first authorize your application. A "User" may be just your App trying to create events, upload images etc that needs authentication. In this case you'll just have to go through the process once and then you'll have your access token. In the case of your app wanting to login with real Eventful users you'll have to do the following once for every user that wants to be authenticated. The process of authorizing an application has three separate steps,

  1. The application gets a request token.
  2. The user authorizes the request token by logging into Eventful.
  3. The application exchanges the request token for an access token.

The access token is all your application needs in order to access protected API resources. The access token will not automatically expire, but access can be revoked at any time by the user or Eventful. If the access token is revoked you may repeat the authorization steps to acquire a new access token.

These endpoints handle the authorization process,

Request Token
POST http://eventful.com/oauth/request_token
Authorize Request Token
GET http://eventful.com/oauth/authorize
Access Token
POST http://eventful.com/oauth/access_token

Please note:

  • The Request Token and Access Token endpoints only accept POST requests.
  • All oAuth requests must be signed with HMAC-SHA1 signatures.
  • All oAuth requests must contain timestamp and nonce parameters.
  • If you get a 404 when requesting data you are probably either making a GET request when a POST Is required, not sending the correct parameters, or are not computing the signature with the correct parameters. If you have problems please enter in all relevant parameters into this form and see what signature it computes. Compare it with what signature you are actually sending. Rember to enter in your app_key and any other parameters you send into the parameters line and set the HTTP method to the correct value. For the initial request token live the token and token_secret blank.

oAuth Example

The consumer, request token, and access token in this example are for illustration only, they will not work for real requests. Substitute your own consumer to test your client implementation.

We need a consumer key and consumer secret to identify our consumer.

Consumer Key
fe29a8e561b3d15803
Consumer Secret
97edfe539abbdd4f8aa2

First we need to get a request token from Eventful. We must specify a callback URL which will be used later by the authorization step.

Method
POST
Resource
http://eventful.com/oauth/request_token
Callback URL
http://example.com/callback
Timestamp
1336765460
Nonce
1cdb7f498ba9811513f2
> POST /oauth/request_token?oauth_callback=http%3A%2F%2Fexample.com%2Fcallback&oauth_consumer_key=bafe29a8e561b3d15803&oauth_nonce=1cdb7f498ba9811513f2&oauth_signature=8EfteAvDBuE8MTVBABg2WhXnzY0%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1336765460&oauth_version=1.0 HTTP/1.1
> Host: eventful.com
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-length: 102
< Content-Type: text/html; charset=UTF-8
oauth_token=a2f0ff589d81971049f5&oauth_token_secret=b2e399a290de4ddef47b&oauth_callback_confirmed=truev

Now we have a request token.

Reqest Token
a2f0ff589d81971049f5
Request Token Secret
b2e399a290de4ddef47b

We must now forward the user's web browser to the authorization endpoint to authorize the request token.

Method
GET
Resource
http://eventful.com/oauth/authorize
http://eventful.com/oauth/authorize?oauth_token=a2f0ff589d81971049f5

The user will be prompted to authorize the consumer, that is, our application. Once their identity is confirmed and authorization is complete, Eventful redirects the user back to the callback with a oauth_verifier parameter.

http://example.com/callback?oauth_token=a2f0ff589d81971049f5&oauth_verifier=18b1274f229e43152a2b

We use the oauth_verifier to exchange the request token for an access token.

Method
POST
Resource
http://eventful.com/oauth/access_token
Request Token Verifier
18b1274f229e43152a2b
Timestamp
1336765614
Nonce
02c943977f5c9fd404bd
> POST /oauth/access_token?oauth_consumer_key=bafe29a8e561b3d15803&oauth_nonce=02c943977f5c9fd404bd&oauth_signature=K44I4kgqSQL5k05m4MdNP1dLSv4%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1336765614&oauth_token=a2f0ff589d81971049f5&oauth_verifier=18b1274f229e43152a2b&oauth_version=1.0 HTTP/1.1
> Host: eventful.com
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-length: 72
< Content-Type: text/html; charset=UTF-8
oauth_token=f1a1b7d55226d2fafd76&oauth_token_secret=2ee984ea96581a99a7a1

Now we have an access token.

Access Token
f1a1b7d55226d2fafd76
Access Token Secret
2ee984ea96581a99a7a1

We may now request the user's protected resources. In this case, we list their saved locations.

Method
GET
Resource
http://api.eventful.com/rest/users/locales/list
Timestamp
1336776486
Nonce
fe639103d4752c844661
> GET /rest/users/locales/list?app_key=test_key&oauth_consumer_key=bafe29a8e561b3d15803&oauth_nonce=fe639103d4752c844661&oauth_signature=rXMxiIv7fyHcztzdLxW3CLTcaBQ%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1336776486&oauth_token=f1a1b7d55226d2fafd76&oauth_version=1.0 HTTP/1.1
> Host: api.eventful.com
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-type: text/xml; charset=utf-8
< Content-length: 12937
<?xml version="1.0" encoding="UTF-8"?>

<locales>
  <locale>
    <name>San Diego metro area</name>
    <location_type>metro_id</location_type>
    <location_id>1</location_id>
    <modified></modified>
  </locale>
</locales>