3-Legged OAuth Authentication (OAuth 1.0 only)
Full 3-legged OAuth, available through
FatSecret.com, allows you, the developer, to provide your application to users who are members of
FatSecret.com. This facility allows users to approve your application to act on their behalf without sharing their FatSecret.com account credentials with you.
Use this mechanism to attain a valid access token for a profile that is directly linked to a user account on FatSecret.com (instead of creating your own profiles
for users), so you can build whatever applications and services you wish for existing members.
The full OAuth flow can be found at
OAuth Core 1.0 Revision A. You will be required to sign requests using the OAuth
protocol so please take some time to read our guide to
Authentication.
Authenticating with OAuth
The steps involved in getting user authentication are as follows:
Step 1. Obtaining a Request Token
The application makes a signed request to the Request Token URL to obtain an unauthorized Request Token. Create the signature base string with the following:
- HTTP Method
- We support both HTTP methods GET and POST.
- Request Token URL
-
The URL to obtain an unauthorized Request Token is https://www.fatsecret.com/oauth/request_token
- Normalized Parameters
- oauth_consumer_key
- Your consumer key (you can obtain one by registering here)
- oauth_signature_method
- We only support "HMAC-SHA1"
- oauth_timestamp
- The date and time, expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value must be a positive integer and must be equal or greater than the timestamp used in previous requests
- oauth_nonce
- A randomly generated string for a request that can be combined with the timestamp to produce a unique value
- oauth_version
- Must be "1.0"
- oauth_callback
- An absolute URL to redirect the User to when they have completed Obtaining User Authorization. Set to "oob" (out-of-band configuration) if you are unable to receive callbacks.
The response from a successful request contains the following parameters:
- oauth_token
- The Request Token
- oauth_token_secret
- The Request Token Secret (required in Step 3)
- oauth_callback_confirmed
- Set to "true" to confirm that the callback value was received
Step 2. Obtaining User Authorization
The User must authorize the Request Token before it can be exchanged for an Access Token. To obtain approval you must direct the User to the User Authorization URL.
- User Authorization URL
-
The URL to authorize a Request Token is https://www.fatsecret.com/oauth/authorize
You must construct an HTTP GET request to User Authorization URL with the following parameters:
- oauth_token
- The Request Token obtained in Obtaining a Request Token.
The User will now be asked to authorize your application to access their private resources. The User will be presented with the following screen:
Figure 1: User already logged in
Figure 2: Sign in screen
The User is redirected to the callback URL once they have authorized or denied the Request Token with the following parameters added:
- oauth_token
- The Request Token that the User authorized or denied
- oauth_verifier
- The verification code
If you did not provide a callback URL, the verification code is displayed for the User. You must be able to allow the User to input the verification code.
Figure 3: No callback URL provided. The User is shown the verification code
Step 3. Obtaining an Access Token
The application makes a signed request to the Access Token URL to exchange an authorized Request Token for an Access Token. The Access Token can now be used to access an
existing FatSecret member's private resources. Create the signature base string with the following:
- HTTP Method
- We support both HTTP methods GET and POST.
- Access Token URL
-
The URL to obtain an unauthorized Request token is https://www.fatsecret.com/oauth/access_token
- Normalized Parameters
- oauth_consumer_key
- Your consumer key (you can obtain one by registering here)
- oauth_token
- The Request Token obtained in Obtaining a Request Token which has been authorized
- oauth_signature_method
- We only support "HMAC-SHA1"
- oauth_timestamp
- The date and time, expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value must be a positive integer and must be equal or greater than the timestamp used in previous requests
- oauth_nonce
- A randomly generated string for a request that can be combined with the timestamp to produce a unique value
- oauth_version
- Must be "1.0"
- oauth_verifier
- The verification code received from Obtaining User Authorization
NOTE: As with any request where you pass in the
oauth_token parameter, you must also sign the request with the
oauth_token_secret (obtained in
Obtaining a Request Token).
The
key to sign the request is the concatenated values of the Consumer Secret and
oauth_token_secret separated by an '&' character (refer to Step 2 in
Authentication).
The response from a successful request contains the following parameters:
- oauth_token
- The Access Token
- oauth_token_secret
- The Access Token Secret
The results from this call should be saved and subsequently used to provide ongoing storage to users of your site or service. You are obliged to ensure that the values are held
securely and to not disclose any oauth_secret values. You should maintain the relationship between your users and the token and secret values you allocate for them.