In web-based applications, the server is the primary connection point to Fire Eagle. For each user that wants to authorize your app, the following illustrates the authorization flow.
|
Obtaining an unauthorized request token
Request Token URL
https://fireeagle.yahooapis.com/oauth/request_token
Required Parameters:
oauth_consumer_key : application consumer keyoauth_callback : the callback URL.oauth_nonce, oauth_timestamp, oauth_signature_method, oauth_version, oauth_signature
Your users are not involved in this step. First, your application makes an API call to Fire Eagle for a request token. Note that the oauth_signature you generate for this call will use only your oauth_consumer_key as a key. Fire Eagle will respond with a unique request token.
Fire Eagle's response will look something like:
oauth_token=jw99864fjif4&oauth_token_secret=fc3y9mdkffnb4b5j0qq&oauth_callback_confirmed=true
The oauth_token and oauth_token_secret are both required components of the request token.
This request token is temporary for this user authorization session.
The oauth_callback_confirmed is a mandatory parameter to be returned by the server to identify that it can handle the new OAuth standard.
|
|
Obtaining user authorizations
User Authorization URL
https://fireeagle.yahoo.net/oauth/authorize
Required Parameters:
oauth_token : the request_token that you obtained in the previous step
After obtaining the request token, your application constructs the authorization URL to call Fire Eagle with the request token. The oauth_token parameter is the request token from the response in step 1. The oauth_token_secret from step 1 is appended to your oauth_consumer_secret to create a key for generating the oauth_signature.
You get the user's browser pointed at the authorization URL where he or she can choose whether to authorize your application or not. If the user authorizes your application, Fire Eagle will invoke your application callback URL that you passed as oauth_callback in the step 1. The invoked URL will have the request token and an oauth_verifier appended as parameters.
|
|
Obtaining user-specific access token
Access Token URL
https://fireeagle.yahooapis.com/oauth/access_token
Required Parameters:
oauth_consumer_key : application consumer keyoauth_verifier : received through the callback URL in step 2.oauth_token : the request_token passed to your application callback URL by FE. This should be the same as the request_token you obtained in step one.oauth_nonce, oauth_timestamp, oauth_signature_method, oauth_version, oauth_signature
After the user authorizes your application, your application needs to exchange the request token for a permanent user-specific access token, access token for short. Regardless of the application type, the access token uniquely identifies the user to your application, represents the permissions the user has authorized to your application and allows your application to update or query Fire Eagle for the user's location information on behalf of the user.
To get the access token, the callback URL registered with your application will be called by Fire Eagle with the request token after the user authorizes your application. At this point, your application needs to make an API call to Fire Eagle with the request token. Similar to step 2, the oauth_token parameter is the request token token, while the request token's oauth_token_secret is appended to your oauth_consumer_secret to create a key for generating the oauth_signature.
If the user has properly authorized your application, Fire Eagle will respond with a unique access token for the user. Fire Eagle will respond with something like:
oauth_token=1q3kfvcmei74&oauth_token_secret=68xedxj4cbwov5agufgea3v1z80p16s3
The oauth_token and oauth_token_secret passed back in this step are the the access token for this user. You will no longer need to worry about the request token (for this user).
|
|
Managing and storing the access token
You will receive an access token and access secret for the user which you need to store together securely. The access token ties the user to your application and is your pass to update and query for the the user's location within Fire Eagle. You need to figure out how your application associates the access token with your application's representation of the user. The access secret is used to sign your application's query and update requests for the user.
For server-based applications, access tokens and access secrets should be treated as private data on your web server. Protect this data from the public as the corresponding user's location information may be inadvertently exposed if the user's access token and access secret are compromised. User-specific access tokens should be considered as the property of your users.
|