FatSecret Platform API Documentation

OAuth 2.0

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

User
You (the developer)
Client
Your application
Client ID
A value we issue to you which helps us identify you
Client Secret
A secret we issue to you which helps us establish that it really is you
Scope
The FatSecret API resources that an Access Token can access. You can request more than one scope (space delimited) per token. For example if you need to do a localized food.find_id_for_barcode* call the scope would be "premier barcode localization".
Access Token
A generated access token which allows Clients to access certain FatSecret API resources depending on the Scope specified
Valid Scopes

Below is a list of valid scopes

  • basic
  • premier
  • barcode
  • localization
  • nlp
  • image-recognition

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.

Access Token URL
https://oauth.fatsecret.com/connect/token
grant_type
We only support "client_credentials"
client_id
Your Client ID
client_secret
Your Client Secret
scope
Valid scopes are "basic", "premier", "barcode" and "localization". You can request any combination of scopes that your Client has access to (e.g: "premier barcode localization" to do a localized food.find_id_for_barcode* call)
Request Example

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