FatSecret Platform API Documentation

This guide is a summary of the main prerequisites of the OAuth Core 2.0 protocol used for signing FatSecret Platform REST API requests.

Valid Scopes

Below is a list of valid scopes

NOTE: If no scope is specified then all scopes you have access to will be sent.

Requesting tokens using a proxy server

FatSecret requires that OAuth 2.0 tokens be requested through a proxy server. This ensures that client credentials can be properly secured (off individual devices for example) and has benefits in manageability of tokens for developers. The improved security with this approach protects the API resources for all users. What this means is that tokens can only be requested from a finite number of IP addresses that you will be able to specify when managing your keys once you register an application. For PREMIER and PREMIER Free level you will be able to specify IP ranges in CIDR notation.

Making a request

FatSecret supports the 'Client Credentials' grant type to secure server-to-server communication. Clients are allocated two pieces of information to be able to make requests: the Client ID and Client Secret. With these credentials the client can request an Access Token for accessing FatSecret API resources.

1. Request a Client ID and Client Secret from FatSecret
2. Request an access token
3. Using the access token to call an API
4. Refresh an access token

Step 1. Request a Client ID and Client Secret from FatSecret

Register an application and you will be provisioned a Client ID and Client Secret.
NOTE: You must make a copy of your Client Secret as it is displayed only once and it cannot be retrieved later.

Step 2. Request an access token

The Client makes a request to the Access Token URL for an access token.

Request Example

• curl
• Node.js
• C#

-u <YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>
-d "grant_type=client_credentials&scope=basic"
-X POST https://oauth.fatsecret.com/connect/token

var request = require("request");
clientID = 'YOUR_CLIENT_ID'
clientSecret = 'YOUR_CLIENT_SECRET'

var options = {
   method: 'POST',
   url: 'https://oauth.fatsecret.com/connect/token',
   method : 'POST',
   auth : {
      user : clientID,
      password : clientSecret
   },
   headers: { 'content-type': 'application/x-www-form-urlencoded'},
   form: {
      'grant_type': 'client_credentials',
      'scope' : 'basic'
   },
   json: true
};

request(options, function (error, response, body) {
   if (error) throw new Error(error);

   console.log(body);
});
            

var client = new HttpClient();
var byteArray = Encoding.ASCII.GetBytes("YOUR_CLIENT_ID:YOUR_CLIENT_SECRET");
client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));

var values = new Dictionary<string, string>
{
   { "scope", "basic" },
   { "grant_type", "client_credentials" }
};
var content = new FormUrlEncodedContent(values);
var response = await client.PostAsync("https://oauth.fatsecret.com/connect/token", content);

var responseString = await response.Content.ReadAsStringAsync();
            

Response Example

The response contains a signed JSON Web Token which contains the type (Bearer) and how much time before the token expires expressed in Unix time (86400 seconds, which means 24 hours)

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token":"eyJhbGciOiJSU... ENjJEM ",
   "token_type":"Bearer",
   "expires_in":86400
}

* expires_in: The lifetime in seconds of the access token from the time the response was generated (86400 = 60*60*24 = one day)

If you decode the access_token you will see that it contains the following claims:

{
   "nbf": 12345,
   "exp": 67890,
   "iss": "https://oauth.fatsecret.com",
   "aud": [
      "https://oauth.fatsecret.com/resources",
      "basic"
   ],
   "client_id": "CLIENT_ID",
   "scope": [
      "basic"
   ]
}

Step 3. Using the access token to call an API

The Client accesses FatSecret API resouces by presenting the access token as part of the request header

Example: Doing a food search (foods.search)

POST https://platform.fatsecret.com/rest/server.api
Content-Type: application/json
Header: Authorization: Bearer <Access Token>
Parameters: method=foods.search&search_expression=toast&format=json

That's it! We will hopefully be able to process the OAuth 2.0 request.

Step 4. Refresh an access token

Clients should store the access token expires_in value and request a new Access Token before the token is expired.