FatSecret Platform API Documentation
OAuth 1.0
This guide is a summary of the main prerequisites of the OAuth Core 1.0 protocol used for signing FatSecret Platform REST API requests.
Note that we also link to Libraries that assist you in making REST profile integration API calls.
You MUST include the following parameters in each request when using OAuth1.0
| Name | Type | Required | Description |
|---|---|---|---|
| oauth_consumer_key | String | Required | Your API key when you registered as a developer |
| oauth_signature_method | String | Required | Method used to generate the signature (only HMAC-SHA1 is supported) |
| oauth_timestamp | Int | Required | 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 | String | Required | A randomly generated string for a request that can be combined with the timestamp to produce a unique value |
| oauth_version | String | Required | MUST be "1.0" |
| oauth_signature | String | Required | Signature, a consistent reproducible concatenation of the request elements into a single string. The string is used as an input in hashing or signing algorithms |
Some OAuth Definitions
- User
- You (the developer)
- Consumer
- Your application
- Consumer Key
- A value we issue to you which helps us identify you
- Consumer Secret
- A secret we issue to you which helps us establish that it really is you
- Access Token
- A value which identifies a user of your application (you use the REST API Profile Management methods to generate these)
- Access Secret
- A secret we issue with the Access Token which helps us establish that you can perform a request on behalf of the user identified by the Access Token (you use the REST API Profile Management methods to generate these and/or retrieve these for your users).
Making a request
The basic steps involved in correctly signing and making requests are as follows:
Step 1. Creating a Signature Base String
You generate a Signature Base String by concatenating the HTTP method (GET or POST), the Request URL, and your query parameters in the following format:
<HTTP Method>&<Request URL>&<Normalized Parameters>
- HTTP Method
- We support both HTTP methods GET and POST.
- Request URL
-
The URL to make API calls is https://platform.fatsecret.com/rest/server.api
- Normalized Parameters
-
Please refer to the FatSecret REST API documentation for the full parameter list for each method, but for OAuth authentication the following parameters are required for every request:
- 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"
-
Parameters are written in the format "name=value" and sorted using lexicographical byte value ordering, first by name and then by value. Finally the parameters are concatenated in their sorted order into a single string, each name-value pair separated by an '&' character (ASCII code 38).
All request parameters (i.e. the HTTP Method, Request URL and Normalized Parameters) must be encoded using the [RFC3986] percent-encoding (%xx) mechanism and concatenated by an '&' character.
E.G.: A request is made using the POST HTTP method with the following parameters:
- oauth_consumer_key=demo
- oauth_signature_method=HMAC-SHA1
- oauth_timestamp=12345678
- oauth_nonce=abc
- oauth_version=1.0
- a=foo
- z=bar
The individual sections of the Signature Base String are:
- Http Method
- POST
- Request URL
- https://platform.fatsecret.com/rest/server.api is encoded to produce
https%3A%2F%2Fplatform.fatsecret.com%2Frest%2Fserver.api - Normalized Parameters
-
First we sort the parameters:
- a=foo
- oauth_consumer_key=demo
- oauth_nonce=abc
- oauth_signature_method=HMAC-SHA1
- oauth_timestamp=12345678
- oauth_version=1.0
- z=bar
Second we concatenate the parameters:
a=foo&oauth_consumer_key=demo&oauth_nonce=abc&oauth_signature_method=HMAC-SHA1&oauth_timestamp=12345678&oauth_version=1.0&z=bar
Third we encode the sorted and concatenated string:
a%3Dfoo%26oauth_consumer_key%3Ddemo%26oauth_nonce%3Dabc%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D12345678%26oauth_version%3D1.0%26z%3Dbar
The request parameters are concatenated with the '&' to produce the Signature Base String:
POST&https%3A%2F%2Fplatform.fatsecret.com%2Frest%2Fserver.api&a%3Dfoo%26oauth_consumer_key%3Ddemo%26oauth_nonce%3Dabc%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D12345678%26oauth_version%3D1.0%26z%3Dbar
Step 2. Calculating the Signature value (oauth_signature)
Use the HMAC-SHA1 signature algorithm as defined by the [RFC2104] to sign the request where text is the Signature Base String and key is the concatenated values of the Consumer Secret and Access Secret separated by an '&' character (show '&' even if Access Secret is empty as some methods do not require an Access Token).
The calculated digest octet string, first base64-encoded per [RFC2045], then escaped using the [RFC3986] percent-encoding (%xx) mechanism is the oauth_signature.
Step 3. Sending the Request
Send all the parameters used to generate the Signature Base String via the HTTP method specified in the Signature Base String, with the inclusion of the oauth_signature.
That's it! We will hopefully be able to generate the same oauth_signature from our end and confirm that it is indeed you.