Fire Eagle : OAuth & Tokens

Fire Eagle uses OAuth for application authentication and authorization. In a nutshell, the OAuth protocol defines the process through which you authenticate your application to Fire Eagle and the process for users to authorize your application to access their location information in Fire Eagle.

The OAuth protocol specifies that all API calls contain token parameters which identify the application and/or the user. There are three types of tokens which you should be concerned about:

Consumer token

This token identifies your application. In Fire Eagle, it is your consumer key and generated when you create a new application. When referring to the OAuth spec, it will be called the consumer token.

Access token

There are two types of access tokens used in Fire Eagle. The access token identifies a user of your application or your application itself. See below for more information.

Request token

This is a temporary token used to initiate user authorization of your application. The request token is exchanged for the access token during the user authorization process.

The consumer key and the access token are passed in API requests for access to user and application data.

• Read more about OAuth

Fire Eagle access tokens

Fire Eagle defines two types of access tokens which are used for different types of API methods. The API method will define what type of access token you need to use in order to generate the OAuth signature for the API request.

User-specific Access Token

This token defines a User's relationship to a Fire Eagle application and is used for user-specific API methods. This is the same access token described in the OAuth spec. It is generated when a user authorizes your application and gives permission for your application to access his or her Fire Eagle location information.

User-specific access tokens are unique for each Application/User pairing and are obtained through the user authorization process. In order to protect the identity of the User, this token is the only value that applications can use to identify Users within the Fire Eagle context (Applications do not know the Yahoo! ID of a user).

General-purpose Access Token

This token defines an application's relationship to Fire Eagle. They are tied to your application and allow your application to make general-purpose API method calls (often batch-style) to Fire Eagle.

When you create a new web-based application, a general-purpose access token is issued to you along with your application key and secret. Along with your consumer key and secret, the general-purpose access token should be kept private and not distributed publicly in any form. General purpose tokens are not issued to mobile and desktop applications.

Due to this token's powerful permissions, there is the potential to reveal a much greater amount of personal data if it is compromised. In an attempt to mitigate this, general-purpose access tokens will be granted only to server-based applications. In addition, developers must provide a restrictive IP range from which the API requests will originate at registration time in order to further reduce the risk of general-purpose tokens being used inappropriately. Contact us with details if you seek an exception.

Expired/Suspended tokens

Access tokens may be expired or disabled by the user or by Fire Eagle. When a token is disabled, you'll get an error message from the Fire Eagle APIs informing you that the token is suspended, permanently disabled, or unrecognized. Unrecognized and permanently disabled tokens are useless and your user will need to go through the authorization steps again so that your application can get a new access token.

Suspended tokens are different from expired tokens. Periodically, Fire Eagle will ask the user whether he or she would like to continue using the applications on Fire Eagle. If the user does not respond, then his access tokens become suspended. In the suspended state, your application will not be able to query or update the user's location. Users can unsuspend their tokens by visiting the Fire Eagle site and confirming that they would like to continue using the applications on Fire Eagle. Your application does not need to get a new access token and the user will not need to go through authorization steps again.

Next: Getting Started 1-2-3