Scopes

Access to Toast APIs, specific endpoints, and specific API endpoint operations is controlled by the scopes that are associated with your API account. Toast API scopes and their capabilities are described below.

To see the scopes associated with your API client, you must decrypt the authentication token you receive after you request an authentication token. For more information about the contents of a Toast API authentication token, see Authentication return data for a partner API client and Authentication return data for a restaurant management group API client.

API client scope reference

The following table describes the scopes that determine what actions your Toast API client has permission to perform.

API	Scope Type	Scope Name	Description
Cash management	Read	cashmgmt:read	Allows reading from the cash management API.
Configuration	Read	config:read	Allows reading from the configuration API.
Credit cards	Write	credit_cards.authorization:write	Allows authorization of payments through the credit cards API.
Kitchen	Read	kitchen:read	Allows reading from the kitchen API.
Labor	Read	labor:read	Allows reading all data except employees from the labor API.
Labor	Read	labor.employees:read	Allows reading employee information from the labor API.
Labor	Write	labor.employees:write	Allows updating employee information in the labor API.
Labor	Write	labor.jobs:write	Allows updating job information in the labor API.
Labor	Write	labor.shifts:write	Allows updating shift information in the labor API.
Menus	Read	menus.channel:read	Allows reading from the menus API V3. Note Ordering partner integrations must use V3 of the menus API, which requires the menus.channel:read scope. Because V3 currently only supports ordering partner integrations, all other integration partners should continue to use menus API V2, which requires the menus:read scope.
Menus	Read	menus:read	Allows reading from the menus API V2. Note Because menus API V3 currently only supports ordering partner integrations, all other integration partners should continue to use menus API V2, which requires the menus:read scope.
Order management configuration	Read	digital_schedule:read	Allows reading from the order management configuration API.
Orders	Read	orders:read	Allows reading from the orders API with the exception of guest information. If your API client creates orders, then to read orders, it must have both the orders:read scope and the orders.channel:read scope.
Orders	Read	orders.channel:read	Allows API clients that submit orders to the Toast platform to read from the orders API. To read orders, the API client must have both the orders:read scope and the orders.channel:read scope. API clients that have the orders.channel:read scope can only read the orders that they submitted. They cannot read orders from any other source.
Orders	Read	delivery_info.address:read	Allows reading guest delivery address information from the orders API.
Orders	Read	guest.pi:read	Allows reading guest and curbside pickup information from the orders API.
Orders	Write	orders.delivery_info:write	Allows updating delivery information from the orders API.
Orders	Write	orders.discounts:write	Allows adding discounts to orders using the orders API.
Orders	Write	orders.items:write	Allows adding items to orders using the orders API.
Orders	Write	orders.orders:write	Allows posting orders orders using the orders API.
Orders	Write	orders.payments:write	Allows adding payments and tips to existing orders using the orders API.
Restaurant availability Restaurants	Read	restaurants:read	Allows reading from the restaurant availability API. Allows reading from the restaurants API.
Stock	Read	stock:read	Allows reading from the stock API.
Stock	Write	stock:write	Allows updating stock status for menu items (and modifier option item references) using the stock API.
Packaging preferences	Read	packaging:read	Allows reading a restaurant's current packaging preferences configuration.

Getting API client scopes

The scopes that give your Toast API client permission to use APIs, endpoints, and endpoint functions are assigned based on your organization's business requirements. Some Toast API scopes are available to all API clients and some scopes are assigned to clients after specific certification of the integration function they are used for.

If your API client does not have the scope required to perform an action, you can contact the Toast integrations team to learn about the requirements for getting access to the scope. The business requirements of your organization and the status of your integration affect the scopes assigned your API client.