Connect OAuth

This reference lists available public methods for our OAuth endpoints for Grocery API. The OAuth Connect flow allows you to customize the user’s experience by passing additional parameters to Foodin. Some common examples are explained below, and the rest of the reference lists every possible option.

Authorize the account

`GET` OAuth for Standard Accounts

/oauth/authorize

Parameters

Parameter	Description
client_id	This is the unique identifier provided to your application, found in your application settings.
response_type	The only option at the moment is code.
redirect_uri (Optional)	The redirect URI for the authorize response in the Grocery API must match one of the pre-configured values in the application's settings. It is important to note that for security purposes, the live mode redirect URI must utilize a secure HTTPS connection. In the absence of a specific redirect URI being defined, the default value from the application's settings will be used.
scope	read_write or read_only, depending on the level of access you need.
state	An arbitrary string value we’ll pass back to you, useful for CSRF protection
client_roles	An array of roles that apply to the connected account.

The following query string parameters are all optional—we use them to prefill details in the account form for new users. Some prefilled fields (for example, URL or product category) might be automatically hidden. Any parameters with invalid values are silently ignored.

Optional parameters

Parameter	Description
foodin_user[email]	The user’s email address. Must be a valid email format.
foodin_user[url]	The URL for the client’s business. This may be the client’s website, a profile page within your application, or another publicly available profile for the business, such as a LinkedIn or Facebook profile
foodin_user[country]	Two-letter country code (for example, US or CA). Must be a country that Foodin currently supports.
foodin_user[phone_number]	The phone number of the business. Has to contain 10 digits. Has to prefill foodin_user[country] with the corresponding country.
foodin_user[business_name]	The legal name of the business.
foodin_user[business_type]	What is the business type. For Standard accounts the value must be one of sole_prop, corporation, non_profit, partnership, or llc.
foodin_user[first_name]	First name of the person filling out a Foodin application.
foodin_user[last_name]	Last name of the person filling out a Foodin application.
foodin_user[dob_day] foodin_user[dob_month] foodin_user[dob_year]	Day (0-31), month (1-12), and year (YYYY, greater than 1900) for the birth date of the person filling out a Foodin application. If you choose to pass these parameters, you must pass all three.
foodin_user[street_address]	Street address of the business.
foodin_user[city]	Address city of the business. To prevent ambiguity, also prefill foodin_user[country] with the corresponding country.
foodin_user[state]	Address state of the business. Must be the two-letter state or province code (for example, NY for a U.S. business or AB for a Canadian one). Must also prefill foodin_user[country] with the corresponding country.
foodin_user[zip]	Address postal code of the business. Must be a string. To prevent ambiguity, also prefill foodin_user[country] with the corresponding country.
foodin_user[product_description]	A description of what the business is accepting payments for.

Response

Parameter	Description
code	An authorization code you can use in the next call to get an access token for your user. This can only be used once and expires in 5 minutes.
scope	read_write or read_only, depending what you passed on the initial GET request.
state	The value of the state parameter you provided on the initial GET request.

Error Response

In case of an error, the user’s browser won’t be redirected except in the case of access_denied. Instead, errors will be returned in a JSON dictionary with the following fields:

Parameter	Description
error	A unique error code per error type.
error_description	A human readable description of the error.
state	The value of the state parameter you provided on the initial GET request.

Complete the connection and get the account ID

Used both for turning an authorization_code into an account connection, and for getting a new access token using a refresh_token.

`POST`

/oauth/token

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.foodin.ai/groceries/apikeys
const foodin = require('foodin')(YOUR_API_KEY');
 
const response = await foodin.oauth.token({
    grant_type: 'authorization_code',
    code: 'ac_123456789',
});
 
var connected_account_id = response.foodin_user_id;

Request

Make this call using your secret API key as a client_secret POST parameter: When converting an authorization code to an access token, you must use an API key that matches the mode—live or test—of the authorization code (which depends on whether the client_id used was production or development).

When using a refresh token to request an access token, you may use either a test or live API key to obtain a test or live access token respectively. Any existing access token with the same scope and mode—live or test—is revoked.

Per OAuth v2, this endpoint isn’t idempotent. Consuming an authorization code more than once revokes the account connection.

Parameter	Description
grant_type	authorization_code when turning an authorization code into an access token, or refresh_token when using a refresh token to get a new access token.
code or refresh_token	The value of the code or refresh_token, depending on the grant_type.
Scope (Optional)	When requesting a new access token from a refresh token, any scope that has an equal or lesser scope as the refresh token. Has no effect when requesting an access token from an authorization code. Defaults to the scope of the refresh token.

Foodin Docs Overview