Quickstart

Two ways#

There are two ways to a token, and you need both:

• Test token: one click in the console, and you query your own test restaurant. Ideal for getting to know the API in two minutes.
• OAuth 2.0: how every restaurant will connect your app later. The owner signs in, agrees, and your app receives tokens for exactly this restaurant.

All you need is a free Flavoso account, no restaurant of your own and no subscription. The examples run with curl, Node.js 18 or newer, Python 3 with requests and PHP 8 or newer.

With the setup assistant#

The quickest way is inside the console itself. If you have no app yet, the console opens the setup assistant, which takes you to your first response in five steps. Until everything is done, it stays on the left under Setup.

1. 1

   Create an app

   Name, where it runs (on your server or on a device at the restaurant) and what it may do. The assistant shows the client secret exactly once.

   Console › Setup

2. 2

   Create a test restaurant

   A restaurant for trying things out, with a sample menu and tables.

3. 3

   Create a test token

   Access to the test restaurant without the OAuth flow.

4. 4

   First request

   GET /me with the token, from your code or right in the browser. The assistant notices the request as soon as it reaches Flavoso and shows the status and the response.

5. 5

   Receive events

   By webhook to your server, or fetched with GET /events. A test order shows that they arrive.

The sections below walk through the same steps by hand, with code for each.

Create an app and a test restaurant#

1. 1

   Create an account

   Via “Free developer account” on the home page of this documentation. If you already have a Flavoso account, just sign in.

   app.flavoso.com

2. 2

   Create an app

   Choose “New app” under Apps in the console: name, client type (confidential for apps with their own server), a redirect URI and the scopes your app needs. Accept the developer terms. The client secret is shown exactly once: copy it right away.

   Console › Apps › New app

3. 3

   Create a test restaurant

   One click creates your test restaurant: a free restaurant for trying things out, with a sample menu and tables. All your apps share it.

   Console › Test restaurant

For the quickstart, the scopes orders:write, menu:write and store:write are enough. All scopes are listed under Scopes.

Way 1: test token#

Under your app's Credentials, “Create test token” issues an access token and a refresh token for your test restaurant, both with your app's scopes. The access token is valid for one hour, the refresh token for 180 days from its last use, and like any refresh token it is replaced on every use. The console shows both exactly once. This also creates the connection between app and test restaurant, exactly as an owner's consent would.

Set the token as the environment variable ACCESS_TOKEN and call GET /me, which returns the connection itself:

# The test token from the developer console (valid for up to one hour)
export ACCESS_TOKEN="flv_at_..."

curl https://api.flavoso.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response names the restaurant, the granted scopes and livemode. In the test restaurant, livemode is always false:

{
  "object": "connection",
  "id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
  "livemode": false,
  "app": {
    "client_id": "flv_app_...",
    "name": "Example POS"
  },
  "tenant": {
    "id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
    "name": "Test restaurant",
    "slug": "test-k7q2m9",
    "timezone": "Europe/Berlin",
    "currency": "EUR",
    "country": "DE"
  },
  "scopes": [
    "orders:write",
    "menu:write",
    "store:write",
    "reports:read"
  ],
  "plan": "pro",
  "rate_limit": {
    "limit": 120,
    "window_seconds": 60
  },
  "created_at": "2026-10-04T17:40:00.000Z"
}

Accept your first order#

1. 1

   Create a test order

   “Create test orders” creates a real order in the test restaurant, as if a guest had placed it. It shows up in the API and triggers webhooks.

   Console › Test restaurant › Orders

2. 2

   Fetch open orders

   GET /orders?status=pending returns the orders waiting for the restaurant.

3. 3

   Accept

   POST /orders/{id}/accept accepts it, like a click in the dashboard. With an Idempotency-Key, a retry is safe.

# The orders waiting for the restaurant ("Create test orders" in the console creates one)
curl "https://api.flavoso.com/v1/orders?status=pending" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Accept one. The same key gives the same result, so a retry is safe.
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: accept-ORDER_ID"

In the console under Test restaurant › Orders, the order is then shown as accepted, and your app's log shows the request with its response.

Way 2: connect with OAuth#

A real restaurant does not hand you a token. Its owner connects your app, so you build the OAuth 2.0 flow with PKCE into it. You try it out with your test restaurant before anyone else sees it.

1. 1

   Create state and PKCE

   Generate a random code_verifier and state, and derive the code_challenge from the verifier (SHA-256, Base64URL).

2. 2

   Send the user to consent

   Send the browser to https://app.flavoso.com/oauth/authorize. Sign in with your account there, pick the test restaurant, press “Connect”.

3. 3

   Exchange the code for tokens

   Flavoso redirects to your redirect URI with code, state and iss. Compare state, then exchange the code at https://api.flavoso.com/oauth/token within 10 minutes.

4. 4

   Make requests

   Call the API with the access_token from the response, exactly as with the test token.

# 1. PKCE: a random code_verifier, its S256 code_challenge and a random state
CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)

# 2. Open this address in a browser, sign in, pick your test restaurant, press "Connect".
#    http://127.0.0.1:8080/callback must be one of your app's redirect URIs. For a
#    confidential app such a loopback address only connects your test restaurant.
echo "https://app.flavoso.com/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=http%3A%2F%2F127.0.0.1%3A8080%2Fcallback&scope=orders%3Awrite&state=$STATE&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

# 3. The browser lands on http://127.0.0.1:8080/callback?code=...&state=...&iss=...
#    Nothing has to listen there. Compare state with $STATE, then copy the code (valid 10 minutes, once).
curl https://api.flavoso.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  --data-urlencode redirect_uri=http://127.0.0.1:8080/callback \
  -d code_verifier=$CODE_VERIFIER

# 4. First request with the access_token from the response
curl https://api.flavoso.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response of the token endpoint:

{
  "access_token": "flv_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "flv_rt_...",
  "scope": "orders:write menu:write store:write reports:read",
  "connection_id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
  "tenant": {
    "id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
    "name": "Pizzeria Example",
    "slug": "pizzeria-example"
  }
}

Everything about client types, redirect URIs, errors and the consent is under Authentication.

Refresh a token#

An access token is valid for one hour. After that, you get a new pair with the refresh token. Every refresh brings a new refresh token, and only the new one stays valid: store it before you use the new access token.

# Access tokens last one hour. The response carries a NEW refresh token: store it.
curl https://api.flavoso.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN

How rotation, the grace period and revocation fit together is explained under Authentication.

Where to go next#

• Set up webhooks so new orders arrive by themselves. A POS without a public address fetches the events instead.
• For a POS: the POS integration guide, end to end.
• Handle errors properly: Errors, Idempotency, Rate limits.
• Once everything works: Review and directory.