Flavoso APIFundamentalsScopes
Scopes
Nine scopes control what your app may do. Write includes read; reservations are available from the Pro plan.
How scopes work
Your app registers in the console which scopes it may request, and asks for them with scope during authorization, separated by spaces. The owner sees them in plain words and agrees to all or none.
Write includes read: with orders:write an app may also read orders. A connection's scopes are listed in the token endpoint's response under scope and in GET /me under scopes.
Only request what your app needs for its purpose. That is exactly what the review checks, and an owner agrees more readily when the list is short.
The nine scopes
| Scope | What the owner reads | What it unlocks | Plan |
|---|---|---|---|
orders:read | See orders | GET /orders, GET /orders/{id}; events order.*. | every plan |
orders:write | Accept, reject and advance orders | Plus accept, reject, cancel, advance and take over: POST /orders/{id}/accept, reject, cancel, status and acknowledge. | every plan |
menu:read | See the menu | GET /menu and the menu lists; events menu.*. | every plan |
menu:write | Edit the menu: dishes, categories, options, prices and availability | Plus PUT /menu, POST /menu/availability and creating, changing and deleting categories, products, option groups and options. | every plan |
store:read | See opening hours, status and tables | GET /store, opening hours, special days, GET /tables, GET /areas; events store.*. | every plan |
store:write | Pause online ordering, change opening hours and lead times | Plus pause and resume, PATCH /store, PUT /store/hours and special days. | every plan |
reservations:read | See reservations | GET /reservations, single reservations, free times, plus GET /tables and GET /areas to resolve table_ids; events reservation.*. | Pro and up |
reservations:write | Create, confirm and change reservations | Plus create, change and set the status. | Pro and up |
reports:read | See sales and revenue figures | GET /reports/sales, GET /reports/products. | every plan |
When a scope is missing
If a scope is missing, the API answers 403 insufficient_scope, and the WWW-Authenticate header names the missing scope. The connection only gets the scope when the owner connects your app again with it.
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="flavoso", error="insufficient_scope", scope="menu:write"
Content-Type: application/json
{
"error": {
"code": "insufficient_scope",
"message": "This connection lacks the 'menu:write' scope.",
"request_id": "req_4f0c2a9d1e7b3c5a8f6d2e10"
}
}Scopes and events
An event shows data, so a connection only receives it with the matching read scope (or the write scope of the same group). This applies to webhooks and GET /events alike.
| Events | Required scope |
|---|---|
order.* | orders:read |
reservation.* | reservations:read |
menu.* | menu:read |
store.* | store:read |
app.* | none, only the connection itself |
Scopes and plans
The API is included in every plan and costs nothing extra. Reservations come with the Pro plan and up: in a restaurant on Starter, the reservation routes answer 403 plan_required, even if the connection has the scope. The consent screen points this out, and GET /me names the plan under plan.
If a restaurant's subscription is not active, all routes except GET /me and DELETE /connection answer 403 account_inactive.
Changing scopes
You change the scopes your app may request in the console. After approval, additional scopes wait for a new review; until then the reviewed list applies.
Existing connections keep their scopes. A connection only gets more scopes when the owner connects your app again with the new scope. Then app.scopes_changed arrives with previous_scopes.
Still unclear? Write to support@flavoso.com and include the id from X-Request-Id. It lets us find your request in the log.