fatsecret Platform API Documentation

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: This API supports HTTP method POST.
Request Token URL: The URL to obtain an unauthorized Request Token is https://authentication.fatsecret.com/oauth/request_token
Normalized Parameters

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://authentication.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: This API supports HTTP method GET.
Access Token URL: The URL to obtain an unauthorized Request token is https://authentication.fatsecret.com/oauth/access_token
Normalized Parameters

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.