FatSecret Platform API Documentation

3-Legged 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:

  1. Obtaining a Request Token
  2. Obtaining User Authorization
  3. Obtaining an Access Token

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
This API supports HTTP method 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 (required in Steps 2 and 3)
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:
authorize logged in image
Figure 1: User already logged in
authorize sign in image
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.

verification code image
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
This API supports HTTP method GET.
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 (see note)
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.