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:
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 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.
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.